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PROGRAMMING INTERFACES 


The majority of this book consists of guidance information to help the system 
programmer diagnose and fix failures in system or application programs. Such 
information should never be used as programming interface information. 


However, this book also contains general-use programming interface 
information. 


General-Use Programming Interfaces: General-use programming interfaces are 
provided to allow a customer installation to write programs that use the services of 
MVS/System Product Version 3. General-use programming interfaces do not have 
significant dependencies on detailed product design or implementation. 


General-use programming interface information is identified by brackets before and 
after the information, as follows: 


| GENERAL-USE PROGRAMMING INTERFACE —_ | 
Description of the interface. 


| snd of GENERAL-USE PROGRAMMING INTERFACE _____ 
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About This Book 


Service aids are programs designed to help system programmers and IBM program 
support representatives diagnose and fix failures in system or application programs. 
The service aids described in this book are designed to assist in identifying the 
symptoms of the problem, gathering relevant data from system data areas to isolate 

the problem to the component level, and analyzing the component to determine the 
cause of the problem. This publication explains how, why, and when to use IBM 
service aids programs. 


The service aids are: | 


¢ GTF (Generalized Trace Facility) - Traces selected system events such as SVC 
and 1/O interruptions. 


e AMBLIST - Formats and prints object modules, load modules, and CSECT 
identification records; maps reenterable load module area. 


¢ AMDSADMP - Operates as a stand-alone program to produce a dump of central 
and virtual storage and processor-related data. 


¢ AMASPZAP - Verifies or replaces instructions or data in a load module. 


e IPCS (interactive problem control system) - Provides installations with the 
expanded capabilities for diagnosing software failures and facilities for 
managing problem information and status. 


Note: IPCS is not discussed in this publication; for information on IPCS, see the 
MVS/ESA Interactive Problem Control System User’s Guide. 


Trademarks 
The following are trademarks of International Business Machines Corporation. 


Enterprise Systems Architecture/370™ 
MVS/ESA™ 

MVS/DFP™ 

MVS/SP™ 


Who Should Use This Book 


This book is intended for anyone who must determine and diagnose system 
problems and debug a failed system. Usually, this person is a system programmer. 
The book assumes that the reader can: 


¢ Code JCL statements to execute programs or cataloged procedures 
e Code in assembler language and read assembler and linkage editor output 
e Understand basic data processing terminology. 
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How This Book Is Organized 


Each service aid is explained in a separate chapter and the chapters are arranged 
in alphabetical order. The chapter headings show the names of the programs 
without the three-character component identifier (such as AMD). This means that 

you should expect to see AMDSADMP referred to as simply SADMP, except in JCL 
examples and other situations where the full name is necessary. 


Note that throughout the text each service aid is referred to by its abbreviated name, 
except where the full name of the program is necessary for technical accuracy. 
Although you may be confused by the abbreviations at first, you will soon find that 
the shorter names are easier to remember because they remind you of the functions 
that the service aids perform. 


Think of the abbreviated names as acronyms, like this: 


GTF - generalized trace facility 

LIST - module listing program 

SADMP - stand-alone dump program 

SPZAP - superzap (data checker and modifier). 


How To Use This Book 


Service aids have three general functions: 


Information Gathering 


¢ To dump central storage, use the stand-alone program SADMP. To dump virtual 
storage, all central storage, and processor-related data, use the high-speed 
version of SADMP. You can use IPCS to view the output of SADMP at the 
terminal or format the output for printing. 


e To trace system events such as SVC and I/O interruptions, use GTF. GTF output 
can be formatted and printed using the GTFTRACE subcommand of IPCS. 


Formatting and Printing: Mapping © 


¢ To summarize and print records in the SYS1.LOGREC data set, use EREP which 
is described in the publication SYS7.LOGREC Error Recording. 


¢ To format and print load modules, object modules and CSECT identification 
records, or to map the reenterable load module area or the link pack area, use 
LIST. 


¢ To format, print, and view SADMP output, other system dumps, and GTF trace 
output, use IPCS. | | 


¢ To process dumps interactively, see /PCS User’s Guide. 


Generating and Applying Fixes 
¢ To apply new releases, PTFs, or user modifications, use SMP. For information 
on SMP, see the references listed under “Related Information” on page xiv. 


e To verify and/or replace instructions in a load module, or data on a direct 
access device, use SPZAP. 


e To initialize the SYS1.LOGREC data set, use IFCDIP00, which is described in the 
publication SYS7.LOGREC Error Recording. 
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Notation for Defining Control Statement Parameters 


The following discussion describes the notations this publication uses in the format 
descriptions. For further coding conventions, see MVS/ESA JCL Reference. 


1. 


On the control statement, code uppercase letters, words, and the following 
characters exactly as they appear in the format description. 


ampersand & 


asterisk 
comma ; 
equal sign = 
parenthesis  () 
period 


; Lowercase letters, words, and symbols appearing in the format description 


represent variables for which you substitute specific information when coding 
the parameter. 


For example, DDN=ddname is the format description for the DDN parameter of the 
LISTLOAD control statement. When you code the DDN parameter, you 
substitute an alphameric character for the word ‘ddname’. 


. Braces {} are a special notation and you never code them on a control 


statement. Braces group related items. 


For example, {IDENT|ALL} is part of the format description of the OUTPUT | 
parameter of the LISTIDR control statement of LIST. When you use LISTIDR, 
code either IDENT or ALL. If you omit the OUTPUT parameter, LIST will assume 
a default of OUTPUT = ALL. 


. Brackets [] are a special notation and you never code them on a control 


statement. Brackets indicate that the enclosed item or items are optional and 
you can code one or none of the items. 


For example, [,MLPA] is part of the format description for the LISTLPA control 
statement. When you code the LISTLPA control statement, you can include 
MLPA or omit it. 


An example of more than one item enclosed in brackets is [S|I|SI], which is. 
part of the format description for the CCW trace option of GIF. When coding the 
CCW trace option, you can include ‘S’ or ‘Il’ or ‘SI’ or omit them all. 


. An ellipsis...(three consecutive periods) is a special notation and you never 


code it on a control statement. An ellipsis indicates that you can code the 
preceding item more than once in succession. 


For example, ASID=(asid1 ... asidn) is a possible response to GTF prompting. 
The ellipsis indicates that you can repeat asid. 


. Underlining is a special notation and you never code it on a control statement. 


When either brackets or braces enclose a group of items, and you do not code 
any of the grouped items, then the underlined item in that group is the default. 


For example, [,SYSUT={unit|SYSDA}] is part of the AMDSADMP macro 
instruction. The brackets indicate that SYSUT is an optional parameter. If you 
code SYSUT, the braces indicate that you can code either unit or SYSDA. If you 
omit both unit and SYSDA, then SYSUT =SYSDA is the default. 
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| IPCS User’s Guide 


| JCL Reference 


| Using Dumps and Traces 


. VTAM Operations | 


Related Information 


Where necessary, this book references information in other books, using shortened 
versions of the book title. The following table shows the shortened titles, complete 
titles, and order numbers of the books you might need while you are using this 
book. 


Application Development Macro MVS/ESA Application Development Macro Reference GC28-1822 
Reference 

Component Diagnosis: Service - | LY28-1846 
Aids 


— DFP: Diagnosis Reference _LY27-9551 


MVS/ESA component pisgnesis and Logic: Service | 
Aids 


_ MVS/ESA Data Facilily Product Version 3: Diagnosis 
Reference 


MVS/ESA Data Facility Product Version 3 Release 2: LY27-9571 
Diagnosis Reference : 
z Initialization and Tuning © MVS/ESA System Programming Libraey: Initialization GC28-1828 
- and Tuning | 
MVS/ESA Interactive Problem Control yee (IPCS) | ~ GC28-1834 


1IPCS Command Reference 


Command Reference 


. IPCS Planning and Customization. | MVS/ESA interactive Problem Control System . ~GC28-1832 | 


3 Planning 


MVS/ESA Interactive Problem Control System (IPCS) 
User’s Guide , 


MVS/ESA JCL Reference. 


MVS/DFP Version 3 Release 2: Managing | Non-VSAM 
Data Sets 


| @C28-1833 


- @C28- 1829. 


| SC26-4557. 
| -@C28-1 852 
- @c28- 1857 


GC28-1815 
GC28-1826 
| LY28-1843 7 


 GC26-4018. 
— $C26-4559 


-$C27-0612 —si| 


. Managing Non-VSAM Data Sets 


_ SPL: Application Development 
~ Guide 


MVS/ESA System Programming Library: Application | 
Development Guide > 


SPL: Application Development 
_ Macro Reference 


MVS/ESA System progesmmlna. Library: Application 
| Development Macro Reference: | | 


MVS/ESA Message Library: System Codes 


| System Codes 


| System Commands — 


MVS/ESA Operations: System Commands. 


MVS/ESA Diagnosis: Using Dumps and Traces 


MVS Data Administration: Utilities _ 
MVS/Data. a Product Version 3 Release 2: 
Utilities 


» Utilities 


Advanced Communications F Function/Virtual 
Telecommunications Access Method Operations 
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PLANNING: 


Planning: 


Dump and 
Services 


GC28-1838 


DIAGNOSIS: 


For Diagnostic 


Diagnosis: 
Using 
Dumps and 
Traces 


LY28-1843 


Data Areas 


LY28-1043 
to 
LY28-1047 


For Component—Specific Information 


lGc28-1832 


Procedures 


Diagnosis: 
System 
Reference 


LY28-1011 


SYS1.LOGREC 
Error 


Recording _ 


GC28-1845 


Messages 


GC28-1814 


IPCS 


User's 
Guide 


GC28-1833 


IPCS 


System 
Messages | 


Command 
Reference 


GC28-1834 


GC28-1812 


x 
| GC28-1813 | 


Data Areas 
Microfiche 


LYB8-xxxx 


(To identify the component, see Basics of Problem Determination) 


Component 


Component 
Diagnosis: 
Module 
Descrip- 
tions 
LY28-1420 


Diagnosis: 
|ABC 


LY28-xxxx 


LY28-xxxx 
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Summary of Changes 


Summary of Changes 
for GC28-1844-2 
MVS/System Product Version 3 Release 1.3 


This edition contains the following new or changed information for MVS/SP 3.1.3. 


New Information 


¢ A new requirement for the JCL that builds the stand-alone dump program. 
System macros that SADMP needs are now in SYS1.MODGEN as well as in 
SYS1.MACLIB, so the JCL must include a SYSLIB DD statement that 
concatenates these two data sets. 


e A new type of partitioned data set (PDS) introduced by MVS/DFP Version 3 
Release 2. Partitioned data sets extended (PDSEs) can consist of source and 
object modules that you might want to format and print. Certain discussions in 
the LIST chapter now include PDSEs, where appropriate. 

Changed Information 
e Minor editorial and maintenance changes. 


e A terminology change: 


Storage — 


This book uses the term central storage for the storage that has been called real 
storage. In the 3090 processor, storage consists of: 


Central storage + expanded storage = processor storage 


Virtual storage consists of pages contained in processor storage and auxiliary 
storage. 


Summary of Changes 
for GC28-1844-1 
as updated December 1988 


This edition contains the following new or changed information: 
e Changes to GTF (APARs OY13937, OY14565, and UY14566). GTF now: 


— Allows users to address the data for the ASM CCWs 
— Gives users more control over the buffers that GIF uses 
— Increases the tape block size for GIF data sets going to tape. 


¢ Minor editorial and maintenance changes. 


Do not use the new GTF functions until the PTFs for the cited APARs are installed. 
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Summary of Changes 

for GC28-1844-0 

as updated September 16, 1988 

by Technical Newsletter GN28-1259 


This newsletter contains an update for AMASPZAP. 


Summary of Changes 
for GC28-1844-0 
MVS/System Product Version 3 Release 1.0 


This book contains information previously presented in MVS/Extended Architecture 
Service Aids, GC28-1159. The following summarizes the changes to that 
information. 


Changed Information: All the chapters, headings, figures, and so forth, have been 
altered to accommodate the elimination of Print Dump. 


Deleted Information: Chapter 3, Print Dump, has been deleted. All references to 
Print Dump have been removed or changed to reference appropriate replacement 
information. 


Chapter 1. GTF 


Introduction 


The generalized trace facility is a service aid program that is available for 
determining and diagnosing system problems. GTF records system and 
user-defined program events. Through GTF you can trace: 


e Any combination of system events, such as all I/O interruptions and all SVC 
interruptions 


e Specific incidences of one type of system event, such as all I/O interruptions on 
one particular device 


e User-defined events which are generated by the GTRACE macro. 
GTF produces output trace records of system events, subsystem events, and user 
events directed to buffers in virtual storage. The user may also direct output to a 
data set (IEFRDER). IPCS may be used to format, display, and print the GTF output. 
See /PCS User’s Guide for further information about using IPCS to process GTF 
output. 
The following apply to GTF 31-bit addressing support: 


¢ GTF receives control from all branch callers in 31-bit eae mode, 
regardless of where the caller resides in storage. 


e GTF 31-bit support allows the tracing of user and system data above 16 
megabytes. 


¢ Users can issue the GTRACE macro in either 24- or 31-bit addressing mode. 
However, a user must execute in 31-bit mode to trace data above 16 megabytes. 


Notes: 


e GTF traces events on all processors regardless of the specification for GTF on 
the AFFINITY macro during system generation. 


¢ Installations can run with both system. trace and GTF active. Starting GTF does 
not alter the status of system trace. 
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Using GTF 


Features of GTF 


GTF is an integral part of the system defined at system generation and runs as a 
system task. | 


GTF provides many features to allow you to trace a variety of system and user 
events. You can trace channel programs and associated data for start subchannel 
and resume subchannel operations and I/O interruptions by means of the CCW trace 
option. PCI causes GTF to record intermediate status interruptions in the same. 
format that GTF uses to create other I/O trace records. GTF can also record system 
recovery routine operations including STAE/ESTAE operations through the RR 
option. For a complete summary of GTF trace options see the topic “GTF Trace 
Options” on page 1-9. 


Note: For special considerations in the use of GTF to trace events in indexed VTOC 
processing, see DFP: Diagnosis Reference. 


GTF Trace abies 


For the DSP, EXT, PI, RNIO, RR, SRM, and SVC options, GTF produces system trace 
records with two kinds of format: comprehensive and minimal. For all other GTF _ 
options, GTF produces trace records in only one format. To see what the records 
contain for each record type, see Using Dumps and Traces. 


GTF writes trace record output in a trace table in virtual storage (internal mode) and | 
can also write to the IEFRDER data set on an external storage device (external or 
deferred mode). The external storage device can be either a tape or a direct access 
device. When the trace records fill up the internal trace table or the data set, GTF 
overlays previously stored or written output beginning at the oldest buffer or 
physical block. 


om GTF Trace Output 


1-2 Service Aids 


IPCS makes it possible to format and print internal and external GTF trace records 
or to view them at the terminal. In addition, you may format and print the trace 


_ records generated by the GTRACE macro. For information on using the GTRACE — 


macro, see SPL: Application Development Macro Reference. 


lf you request that trace data be included in an ABEND, SNAP, SVC, or stand-alone 
dump, and if GTF is active, you can use IPCS to format the records created by 
GTRACE. Formatting occurs independently of the trace mode or options for GTF. 
You control the number of buffers that GTF formats when you specify the ABDUMP, 
SDUMP or SADMP parameter in the START GTF command. Also, for ABEND and 
SNAP dumps, only those records directly associated with the failing address space 
are formatted. GTF does not format the channel program trace data associated with 
the failing address space in ABEND and SNAP dumps. 


How to Start GTF 


You invoke GTF as a system task in an address space by entering a START 
command from the operator’s console; you cannot start GTF as a job. Using the 
START command, you select the GTF cataloged procedure or your own cataloged 
procedure. Optional parameters in the cataloged procedure and START command 
allow you to specify internal or external tracing, timestamps on records, what action 
should occur if GTF encounters an error during processing, and the number of 
buffers which are to appear on ABDUMP/SNAP or SVC dumps. If you specify one or 
more of the START command parameters, the EXEC parameters from the 
catalogued procedure are ignored. To select the trace options, you either specify 
each option directly through the console or retrieve (via the cataloged procedure) a 
set of previously stored options which exist as a member of SYS1.PARMLIB. 


How to Specify the START Command 


Figure 1-1 shows the general format of the START command as it is used to invoke 
GTF. Since all messages go to the master console, (also called the integrated 
operators console), the START command should be entered only from a console 
eligible to be a master console. 


{START |S}{GTF|procname}[.identifier][,devname][,volserial |] 
[,(parm[,parm]...)][,MEMBER={GTFPARM|userparm} ] 
[,keyword=option[,option]...] 


devname and volserial are positional parameters all other parameters are 
keyword parameters. When you omit a positional parameter and code any 
keyword parameters, you must indicate the absence of the positional parameter 
by coding a comma in place of the positional parameter. 


Figure 1-1. General Format of the START Command for GTF 


The descriptions below explain the parameters of the START command as they are 
used by GTF: 


GTF 
indicates the name of the IBM-supplied cataloged procedure that invokes GTF. 


procname 
identifies the name of the user-written cataloged procedure that you write to 
invoke GTF. 


identifier | 
specifies the user-specified name identifying this GIF session. 


devname 
specifies the device number or the device type of an output device to contain the 
trace data set. If you do not specify a device number or.device type on the 
START command, GTF uses the device number provided on the IEFRDER DD 
statement in the cataloged procedure. devname is a positional parameter. 
When you omit devname and code any keyword parameters, you must code a 
comma to indicate the absence of devname. 
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volserial | 
indicates the serial number of a magnetic tape or direct access volume which is / 
to contain the trace data set. volserial is a positional parameter. When you 
omit volserial and code any keyword parameters, you must code a comma to 
indicate the absence of the volserial. 


(parm) 
overrides the vaiue specified in the PARM= parameter of the EXEC statement 


in the cataloged procedure and may contain any combination of the following 
parameters: 


(Lparm][,parm] ...) 


where parm is one of the following: 


MODE={ INT | EXT | DEFER} 
SADMP={nnnnnnk | nnnnnnM | 40K} 
SDUMP={nnnnnnk|nnnnnnM| 40K} 
ABDUMP={ nnnnnnk| nannnnM| OK} 
BLOK={nnnnn| 10} 
TIME={YES|NO} 

DEBUG={YES |NO} 


MODE = {INT|EXT|DEFER} | 


defines where GTF maintains the trace data. MODE=INT causes GTF to. 
maintain the trace data in the GTF address space. MODE=EXT causes GIF to — 

_ maintain the trace data in an external data set that is defined by the IEFRDER 
DD statement in the cataloged procedure. MODE =DEFER causes GTF to 
maintain the trace data in the GTF address space until the STOP GTF command 
is issued. Then, during its termination processing, GTF transfers the data from 
the GTF address space to the GTF output data set. 


When you code the START command without any parameters, GTF obtains the 
MODE = parameter from the EXEC parameter in the cataloged procedure. The 
default is MODE = EXT. 


When tracing to an external device, you can use IPCS to format data in the trace 
data set. 


{SADMP|SA} = {nnnannnK/[nannnnM|40K} 
allows you to specify the amount of storage you need to save GTF trace data for 
stand-alone dumps. You must specify the amount of storage in terms of either K 
(kilobytes) or M (megabytes). The minimum amount is 40K, and the maximum 
is 2048M-400K; the amount you specify is rounded up to 4K boundaries for 
DASD data sets, or 32K boundaries for tape data sets. 


Instead of the BUF= parameter, use the SADMP= parameter on the START 
GTF command. The system ignores BUF= and uses the defaults for the 
SADMP =, SDUMP=, or ABDUMP= parameters. | 


When you code the START command without any parameters, GTF obtains the 
SADMP= parameter from the EXEC parameter in the cataloged procedure. The 
default is 40K if the GTF data set is on DASD, or 64K if the GTF data set is on 
tape. 


If the system takes a stand-alone dump, you can use IPCS to format this storage. 


{SDUMP|SD} = {nnnnnnK|nnnnnnM|40K} 
allows you to specify the amount of storage you need to save GTF trace data for 
SVC dumps. You must specify the amount of storage in terms of either K 
(kilobytes) or M (megabytes). The minimum amount is zero, and the maximum 
cannot exceed the maximum amount of storage defined by the SADMP = 
parameter. The amount you specify is rounded up to 4K boundaries for DASD 
data sets, or 32K boundaries for tape data sets. 


Instead of the BUF= parameter, use the SDUMP= parameter in conjunction 
with SADMP= and ABDUMP= onthe START GTF command. The system 
ignores BUF= and uses the defaults for the SADMP =, SDUMP =, or 
ABDUMP = parameters. 


When you code the START command without any parameters, GTF obtains the 
SDUMP~ parameter from the EXEC parameter in the cataloged procedure. The 
default is 40K if the GTF data set is on DASD, or 64K if the GTF data set is on 
tape. 


If the system takes an SDUMP, you can use IPCS to format this storage. 


{ABDUMP|AB} = {nnnnnnK|nnnnnnM|40K} 
allows you to specify the amount of GTF data to be formatted in an ABEND or 
SNAP dump. You must specify the amount of data in terms of either K 
(kilobytes) or M (megabytes). The minimum amount is zero, and the maximum 
cannot exceed the maximum amount of storage defined by the SADMP = 
parameter. The amount you specify is rounded up to 4K boundaries for DASD 
data sets, or 64K boundaries for tape data sets. 


Instead of the BUF= parameter, use the ABDUMP= parameter in conjunction 
with SADMP= and SDUMP= on the START GTF command. The system ignores 
BUF= and uses the defaults for the SADMP =, SDUMP=, or ABDUMP = 
parameters. 


When you code the START command without any parameters, GTF obtains the 
ABDUMP= parameter from the EXEC parameter in the cataloged procedure. 
The default is zero, which means that no GTF data will appear in SNAP or 
ABEND dumps. 


If the system takes an ABEND or SNAP dump, you can use IPCS to format this 
storage. 


BLOK = {nnnnn|10} 
allows you to specify the number (1 to 99999) of pages of common storage to 
contain the GTF trace records. The pages of storage will reside in ESQA. 


When you code the START command without any parameters, GTF obtains the 
BLOK= parameter form the EXEC statement in the cataloged procedure. The 
default is 10 pages of storage. 


TIME = {YES|NO} 


YES 
requests that every trace record be time-stamped in addition to the block 
time stamp associated with every block of data. The time stamp is the 
8-byte TOD clock value at the local time the record is put into the trace 
buffers. (TOD clock values are described in Principles of Operation.) 


When TIME = YES is specified and trace records are formatted and printed 
by IPCS, a timestamp record follows each trace record. These timestamp 
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records can be used to calculate the elapsed time between trace entries. 
_ The timestamp record is described in Using Dumps and Traces. 


When you code the START command without any parameters, GTF obtains 
the TIME= parameter from the EXEC parameter in the cataloged 
procedure. The default is TIME =NO. 


NO 
requests no time stamping of individual trace records. That is, no time 
stamp recording or place-holder is kept for the trace record. 


DEBUG = {YES/NO} 


YES 
requests that all error recovery be bypassed, making_all errors terminate 
GTF. 


When DEBUG = YES is in effect and an error occurs in the tracing process, 
GTF issues an error message and immediately terminates, whether or not 
the error is recoverable. 


When you code the START command without any parameters, GTF obtains 
the DEBUG= parameter from the EXEC parameter in the cataloged 
procedure. The default is DEBUG =NO. 

NO | 
requests that GTF attempt to recover from an error, and continue. 


When DEBUG = NO is in effect ancl an error occurs in the tracing process, 


GTF issues an error message but does not terminate. 
i 


MEMBER = {GTFPARM|userparm} 
specifies the member of SYS1.PARMLIB that contains the GTF trace options. If 
not specified in the START command, the IBM-supplied GTF procedure specifies. 
the SYS1.PARMLIB member GTFPARM. See Figure 1-3 on page 1-7. 


keyword = option 
specifies parameters to override or acld to JCL parameters, especially DD 
parameters, in the IEFRDER DD statement in the cataloged procedure. For | 
example: 


e To specify a different name for the trace data set, code 
DSNAME = newname. 


e To prevent the system from sending mount messages to the operator’s. 
console when specifying MODE = INT, code DSN= NULLFILE. 


¢ To specify an existing data set, code DISP=OLD. (Note: If you specify 
DISP = MOD, GTF will change the data set disposition to OLD.) 


e To specify a REGION parameter, code REG=value K. Note that the 
minimum value is 800 and that “K” must be included. See Figure 1-7 on 
page 1-26 for further GTF storage information. 


Service Aids 


IBM-Supplied Cataloged Procedure 
An IBM-supplied cataloged procedure for GTF is supplied in SYS1.PROCLIB with a 


member name of GTF. The format of the cataloged procedure is shown in 
Figure 1-2. 


//GTF PROC MEMBER=GTFPARM 
//TEFPROC EXEC PGM=AHLGTF,REGION=2880K, TIME=1440, 
PARM=( 'MODE=EXT , DEBUG=NO, TIME=NO' ) 


//TEFRDER ODD DSNAME=SYS1. TRACE, UNIT=SYSDA, 
SPACE=(4096,20) ,DISP=(NEW, KEEP) 
//SYSLIB DD DSN=SYS1.PARMLIB(&MEMBER) ,DISP=SHR 


Figure 1-2. IBM-Supplied Cataloged Procedure 


The following description explains the statements in the cataloged procedure: 


PROC Statement | 
defines the cataloged procedure GTF. 


EXEC Statement 
calls for the execution of AHLGTF. 


IEFRDER DD Statement 
defines the trace output data set, according to the following defaults: the trace 
output data set has the name SYS1.TRACE; it is directed to a direct access 
device with sufficient allocation to allow the data set to contain twenty 4096-byte 
physical blocks. When the primary allocation is filled, recording continues at 
the beginning of the data set. 


Note that the data set and attributes on the IEFRDER may be changed using the 
START command. 


If the TRACE data set is directed to tape on the START command, normal 
end-of-volume processing occurs. 


SYSLIB DD Statement (Optional) 
defines a member in the SYS1.PARMLIB data set that contains GTF options. If 
such a member exists, GIF uses the options in the member. If the member 
does not exist, GIF issues an error message and stops. 


lf you start GTF with a procedure which does not contain a SYSLIB DD 
statement, GTF issues message AHL100A. This message requests that you 
supply trace options through the console. 


IBM-Supplied SYS1.PARMLIB Member 


The GTF cataloged procedure automatically invokes the GTFPARM member of 
SYS1.PARMLIB. Figure 1-3 shows the format of the GTFPARM member in 
SYS1.PARMLIB. The options in GTFPARM cause GTF to record specific events. 
See the topic “GTF Trace Options” on page 1-9 for an explanation of the options. 


TRACE=SYSM,USR,TRC,DSP,PCI,SRM 


Figure 1-3. GTFPARM Member in SYS1.PARMLIB 


Chapter1. GTF 1-7 


How to Specify GTF Trace Options 


You select trace options by either directly specifying each option through the system 
console or retrieving a set of options previously stored as a member of 
SYS1.PARMLIB. When you start GTF using the IBM-supplied cataloged procedure, 
GTF retrieves trace options from the GTF-defined member in SYS1.PARMLIB. If you 


~ set up a GTF cataloged procedure, you may define the SYS1.PARMLIB member and 


GTF retrieves trace options from it. If you do not define options, you must specify 
them directly through the console. 


How GTF Identifies Options in SYS1.PARMLIB 


GTF identifies the options set up in SYS1.PARMLIB by issuing the console messages 
AHL1211 and AHL1031. You have the opportunity either to accept these options or to 
reject them and respecify your own. This sequence appears as: 


AHL1211 SYS1.PARMLIB INPUT INDICATED 
AHL103I TRACE OPTIONS SELECTED -- options from SYS1.PARMLIB 


AHL125A RESPECIFY TRACE OPTIONS OR REPLY U 


Some GTF options cause GTF to prompt you for keywords if you specify these 
options through the system console. If the SYS1.PARMLIB member contains any of 
these options, GTF will not prompt you for keywords; the keywords must also 
appear in the member. | 


If you choose to reject the options in the SYS1.PARMLIB member, you will 
completely override all options specified in that member. Respecifying trace 
options in response to AHL125A is not a method of modifying the options in 
SYS1.PARMLIB. 


If you start GTF with a user procedure that does not contain a SYSLIB DD statement, 
you must reply to supply options to the following message: 


AHL100A SPECIFY TRACE OPTIONS 


How You Indicate Trace Options 


1-8 Service Aids 


To respecify new options or specify options for the first time, you respond to the 
message AHL125A or AHL100A with TRACE = keyword, to indicate events to be 
traced during GTF execution. The format of this response is: 


| TRACE=trace option[ ,trace option]...— 


Note that the trace options you specify determine the GTF storage requirements. 
See Figure 1-7 on page 1-26. 


GTF Trace Options 


You can specify the following trace option values: 


ASIDP 
requests that GTF tracing be limited to a subset of address spaces. ASIDP 
requests GTF prompting for one to five address space identifiers in which you 
want GTF tracing to occur. ASIDP only works when you also specify a GTF 
option that generates tracing, such as SVC or IO. 


CCW 
requests tracing of channel programs and associated data for I/O events. CCW 
is valid only if the other trace options you specify include SSCH, SSCHP, IO, or 
IOP. 


CCWP 
requests tracing of channel programs and associated data for I/O events, and 
requests GTF prompting for the following information: tracing CCWs for SSCH 
operations or I/O interruptions or both; maximum number of CCWs for each 
event; maximum number of bytes of data for each CCW; optional |OSB and EWA 
tracing; and size of the PCl table. For information on responding to GTF 
prompts, see the topic “Prompting” on page 1-13. CCWP is valid only if the 
other trace options you specify include SSCH, SSCHP, IO, or IOP. 


CSCH 
requests recording for all clear subchannel operations. 


DSP 
requests recording for all dispatchable units of work (that is, SRB, LSR, TCB.and 
SVC prologue dispatch events). When you specify both SYSM and DSP, GTF | 
records minimal trace data for DSP. Otherwise, GTF records comprehensive 
trace data for DSP. 


EXT 
requests comprehensive recording for all external interruptions. 


HSCH 
requests recording for all halt subchannel operations. 


lO requests recording of all non-program-controlled I/O interruptions. Unless you 
also specify the PCi trace option, GTF does not record program-controlled 
interruptions. | 


lOP 
requests GTF prompting for specific device numbers for which you want GTF to 
record I/O interruptions. Unless you also specify the PCI trace option, GTF does 
not record program-controlled interruptions. For information on responding to 
GTF prompts, see “Prompting” on page 1-13. 


JOBNAMEP 
requests that GTF tracing be limited to a subset of jobs. JOBNAMEP requests 
GTF prompting for one to five jobnames for which you want GTF tracing to 
occur. JOBNAMEP only works when you also specify a GTF option that 
generates tracing, such as SVC or IO. 


MSCH 
requests recording for all modify subchannel operations. 
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PCI 
requests recording of intermediate status interruptions in the same format as 
other I/O trace records that GTF creates. Specifically, PCl causes GTF to record 
program-controlled I/O interruptions, initial status request interruptions, and 
resume and suspend channel program interruptions. When you select specific 
devices as a result of prompting for I/O events (IOP), GTF records intermediate 
status interruptions only for those devices. PCI only works when you specify 
PCI and the other trace options that you specify include |O, IOP, SYS, SYSM, or 
SYSP. 


PI requests comprehensive recording for all program interruptions (0-255). 


PIP 
requests GTF prompting for those interruption codes for which you want GTF to 
‘record program interruptions. For information on responding to GTF prompts, 
see “Prompting” on page 1-13. 


RNIO 
requests recording of all VTAM network activity. When you specify both SYSM | 
and RNIO, GTF records minimal trace data for RNIO. Otherwise, GTF records 
comprehensive trace data for RNIO. 


Note: For successful processing, VTAM trace must be active. 


RR 7 
requests comprehensive recording of data associated with all invocations of 
functional recovery routines (such as STAE and ESTAE routines). GTF creates a 
trace record describing the activity of the recovery routine when control passes. 
from the recovery routine back to the recovery termination manager (RTM). 


siO 
SIOP 


If you request the SIO or SIOP option, GIF processes your request as a request 
for SSCH or SSCHP. GTF issues message AHL138I to indicate this substitution. 
Subsequent messages refer to the original SIO or SIOP option. 


SLIP 
requests that a trace entry be made each time that a match occurs for a SLIP 
trap with a tracing action specified or each time a SLIP trap with the SLIP 
DEBUG option is checked. The amount of data and the type of SLIP trace record 
to be built is specified on the SLIP command. The SLIP option is not included in 
the specification of SYS or SYSM; it must be specified additionally. 
Specification of the SYS or SYSM option does not affect the data collected on the 
SLIP trace record. 


SRM 
requests recording of trace data each time the system resource manager is 
invoked. When you specify both SYSM and SRM, GTF records minimal trace 
data for SRM. Otherwise, GTF records comprehensive trace data for SRM. 
Further information regarding the use of this option is in /nitialization and 
Tuning. 


SSCH 
requests recording for start subchannel and resume subchannel operations. 


SSCHP 
requests GTF prompting for the specific device numbers for which you want GTF 
to record start subchannel and resume subchannel events. For information on 
responding to GTF prompts, see the topic “Prompting” on page 1-13. 


SVC 
requests comprehensive recording for all SVC interruptions. 


SVCP 
requests GTF prompting for those SVC numbers for which you want data 
recorded. For information on responding to GTF prompts, see the topic 
“Prompting” on page 1-13. 


SYS 
requests recording of comprehensive trace data for all external interruptions 
(EXT), program interruptions (Pl), recovery routines (RR), and supervisor call 
interruptions (SVC). SYS causes recording of all I/O interruptions (lO), start 
subchannel and resume channel operations (SSCH), clear subchannel 
operations (CSCH), halt subchannel operations (HSCH), and modify subchannel 
operations (MSCH). When you specify DSP, RNIO, or SRM in addition to SYS, 
GTF produces comprehensive trace data for those events. 


Note: Specification of SYS, SYSM, or SYSP causes GTF to ignore the following 
trace options if you specify them in any form: CSCH, HSCH, MSCH, SSCH, IO, 
SVC, PI, EXT, RR. 


SYSM 
requests recording of minimal trace data for all external interruptions (EXT), 
program interruptions (Pl), recovery routines (RR), and supervisor call 
interruptions (SVC). SYSM causes recording of all I/O interruptions (lO), start 
subchannel and resume channel operations (SSCH), clear subchannel 
operations (CSCH), halt subchannel operations (HSCH), and modify subchannel 
operations (MSCH). When you specify DSP, RNIO, or SRM in addition to SYSM, 
GTF produces minimal trace data for those events. 


Note: Specification of SYS, SYSM, or SYSP causes GTF to ignore the following 
trace options if you specify them in any form: CSCH, HSCH, MSCH, SSCH, IO, 
SVC, PI, EXT, RR. 


SYSP 
requests recording for the same events as the SYS option, but causes GTF to 
prompt you for selection of specific SVC, 10, SSCH, and PI events that you want 
recorded. When you specify DSP, RNIO, or SRM in addition to SYSP, GTF 
produces comprehensive trace data for those events. For information on 
responding to prompts, refer to the topic “Prompting” on page 1-13. 


Note: Specification of SYS, SYSM, or SYSP causes GTF to ignore the following 
trace options if you specify them in any form: CSCH, HSCH, MSCH, SSCH, IO, 
SVC, PI, EXT, RR. 


TRC 
requests recording of those trace events which are associated with GTF itself. 
Unless you request TRC, the GTF associated events are filtered out and not 
_ recorded. TRC only works when you also specify a GTF option that generates 
tracing, such as SVC or IO. 


USR 
requests recording of all data that the GTRACE macro passes to GTF. You must 
specify USR or USRP if you want to code the GTRACE macro. When you code 
the GTRACE macro but do not specify USR or USRP, GTF ignores the GTRACE 
macro. 
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USRP , 
causes GTF prompting for specific event identifiers (EIDs). See “Prompting” on 
page 1-13. GTF builds an internal table of the EIDs that you specify. The TEST 
parameter of the GTRACE macro tests whether or not tracing is active for the 
EIDs that you specify for USRP. USRP does not limit GTF tracing to those user 
EIDs that you specify. The purpose of USRP is to cause GTF to build an internal 
table of EIDs that GTF uses when you specify TEST = YES on the GTRACE 
macro. 


The GTRACE data consists of user event trace records and/or IBM subsystem 
event records. The subsystems are VTAM, JES2, OPEN/CLOSE/EOV, 
SAM/PAM/DAM, and VSAM. | 


edi Certain GTF Options 
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Figure 1-4 shows those TRACE = options that GTF will not use in combination. If 


you specify two or more options from the same row, GTF uses the option that has 


the lower column number and ignores the other options. For example, if you specify . 
both SYSP and PI (see row D), GTF uses SYSP (column 2) and ignores PI (column 5). 


Figure 1-4. Combining Certain GTF Options 


Prompting 


When you specify ASIDP, CCWP, IOP, JOBNAMEP, PIP, SSCHP, SVCP, SYSP, or 
USRP as trace options, GTF prompts you to supply specific values by the following 
message: | 


AHL101A SPECIFY TRACE EVENT KEYWORDS -- keyword=,...,keyword= 


The keywords in the message correspond to those trace options that cause 
prompting (ASID=, CCW=, lO=, JOBNAME=, PIl=, SSCH=, SVC=, SYS=, or 
USR=). GTF accepts only these keywords in your reply. If you specify SYSP, the 
valid keywords are: 1|O=, lIO=SSCH=, SSCH=, PI=, and SVC=. Specify only 
those keywords for which you want specific event recording. Keywords not 
specified default to cause recording of all events within those classes. 


END is also a keyword and signifies that the event definition is complete. If END is 
not encountered in a reply, GTF prompts the operator to continue specification. 
Event keywords are as follows: 


ASID = (asid1[,asidn ]...[ ,asid5 |) 
specifies one to five address space identifiers in which you want GTF tracing to 
occur. The values ‘asid1’ through ‘asid5’ are hexadecimal numbers from 
X'0001' to the maximum number of entries in the address space vector table 
(ASVT). When you specify ASIDP, GTF traces events for the address spaces you 
specify. If you specify ASIDP, but do not specify ASID= before replying END, 
then no ASID filtering takes place and GTF traces all address space identifiers. 


If you use more than one line to specify ASIDs, GTF stacks your replies until you 
specify the maximum of five ASIDs. Ifa line of your reply contains an error in 
the specification of ASIDs, GTF prompts you to respecify the invalid value, and 
leaves intact the valid stacked values from other lines of your reply. 


Note: If you specify both ASIDP and JOBNAMEP, GTF might trace address 
spaces that ASIDP did not identify. This occurs if the jobs that JOBNAMEP 
identified are running in address spaces that ASIDP did not identify. 


CCW = [(S|i|S1][,CCWN = nnnnn j[,DATA = nnnnn ][,IOSB |[ ,PCITAB =n }) 
specifies different options for tracing channel programs. If you specify COW = 
more than once, GTF uses your last specification of CCW=. 
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If you specify CCWP, but do not specify CCW= before replying END, then the 
following defaults are in effect: 


TRACE OPTIONS SELECTED CCW SUBPARAMETER DEFAULTS 
_ SSCH or SSCHP S 


10 or IOP | | I 


SSCH or SSCHP, SI 
and 10 or IOP 


PCI PCITAB=1 


ANY CCWN=50 


ANY DATA=20 


Examples: | | 
TRACE=I0, CCWP CCW. defaults to: CCW=(I,CCWN=50,DATA=20) 
TRACE=I0P,SSCH,PCI,CCWP CCW defaults to: CCW=(SI,CCWN=50,DATA=20,PCITAB=1) 


Figure 1-5. -CCW Defaults for Selected TRACE Options 


If you specify an option more than once in one line, GTF uses your last specification 
of that option. An exception is that GTF uses your first specification of S, |, or SI. Ifa. 
line contains an error, GTF prompts you to respecify the invalid value. 


S|i|SI 
specifies the type of I/O event for which you want channel programs traced. If 
you specify more than one option, GTF uses the first option that you specified. If 
you do not specify any option, SI_is the default. | 


S_ specifies GTF tracing of channel programs for start subchannel and resume 
subchannel operations. CCW=S only works if you specify SSCH or SSCHP as 
trace options. 


| specifies GTF tracing of channel programs for I/O interruptions, including 
program-controlled interruptions if you specify PCI as a trace option. CCW=I 
only works if you specify lO or IOP as trace options. 


SI specifies GTF tracing of channel programs for start subchannel and resume 
subchannel operations and I/O interruptions. CCW=SIl only works if you specify 
either SSCH or SSCHP and either IO or IOP as trace options. 


CCWN = nnnnn 
specifies the maximum number of CCWs that you want traced for each event. 
The value ‘nnnnn’ is a decimal number. It is defined as any integer from 1 to | 
32767. The default is 50. 


DATA = nnnnn 
specifies the maximum number of bytes of data that you want traced for each 
CCW. The value ‘nnnnn’ is a decimal number. It is defined as any integer from 
zero to 32767. The default is 20. 


GTF treats each CCW that belongs to a chain of ‘data-chained’ CCWs as one 
CCW. Therefore, GTF traces ‘nnnnn’ bytes of data for each CCW on the data 
chain. GTF also traces ‘nnnnn’ bytes of data for each word in an IDAW (indirect 
data addressing word) list. 
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For start subchannel or resume subchannel operations, GIF does not trace data 
for read, read backwards, or sense commands in the channel programs. If the 
skip bit is on, (that is, no data is being transferred) regardless of the type of I/O 
operation, GTF does not trace data for read, read backwards, or sense 
commands. When the data count in the CCW is equal to or less than ‘nnnnn’, 
GTF traces all data in the data buffer. When the data count in the CCW is 
greater than ‘nnnnn’, GTF traces data only from the beginning and end of the 
data buffer. The first half of the traced data is measured from the start of the 
data buffer. The second half of the traced data is measured backward from the 
end of the data buffer. Examination of the traced data shows whether the 
channel compietely filled the buffer on a read operation. 


Note: GTF uses a different CCW tracing method for a data transfer that is in 
progress when an I/O interruption occurs. Instead of using the data count in the 
CCW, GTF tracing depends on the transmitted data count. The transmitted data 
count is the difference between the data count in the CCW and the residual 
count in the CSW. If the residual count in the CSW is greater than the data count 
in the CCW, then GTF traces all of the data in the CCW. When the transmitted 
data count is less than or equal to ‘nnnnn’, GTF traces all of the transmitted 
data. When the transmitted data count is greater than ‘nnnnn’, GTF traces data 
only from the beginning and end of the transmitted data. The first half of the 
traced data is measured from the start of the transmitted data. The second half 
of the traced data is measured backward from the end of the transmitted data. 


lOSB 
specifies tracing of the lOS block (IOSB) and, if available, the ERP work area 
(EWA), for all CCW events. If you do not specify lIOSB, then GTF performs [OSB 
and EWA tracing only when GTF encounters an exceptional condition when 
tracing a channel program. 


PCITAB=n 3 
specifies a decimal number of 100-entry increments that you want GTF to 
allocate in an internal PCI table. The value of ‘n’ is an integer from 1to 9. The 
default is 1 (100 entries). 


The PCI table keeps track of the channel programs that use PCI. One entry in 
the PCI table contains information about a program-controlled interruption in 
one channel program. An entry in the PCI table includes a CCW address and an 
IOSB address. 


GTF initializes an entry in the table when the first program-controlled 
interruption occurs for an lIOSB that represents a channel program requesting 
PCI. For each subsequent program-controlled interruption that occurs when 
tracing channel programs, the address of the first CCW traced is taken from the 
PCl table. When GTF completes tracing for each event, GTF updates the entry in 
the PCI table by changing the CCW address to equal the CSW address minus 
eight bytes. GTF deletes the entry when the channel program terminates. if the 
table is not large enough, GTF writes a message to the trace data set indicating 
that the GTF trace data might be incorrect. 


IO = (devnum1(|,devnumn]...[,devnum50 }) 
specifies one to 50 device numbers (hexadecimal notation) for which you want 
[/O interruptions traced. Ail other 1/O interruptions are filtered out. If you 
specify IOP or SYSP and do not specify |O= in response to the prompting 
messages, no I/O interruption filtering takes place and GTF traces all 
non-program-controlled interruptions. 
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lO = SSCH = (devnum1[,devnumn ]...[,devnum50 |) 
only valid after you request either SYSP, or both IOP and SSCHP; specifies one 
to 50 device numbers for which you want GTF to trace both lO and SSCH events. 
GTF filters out ail other 1|O and SSCH events, except those requested specifically 
by 1O= or SSCH=. 


JOBNAME = (jobname'1|,jobnamen ]...[,jobname5 |) 
specifies one to five jobnames for which you want GTF tracing to occur. The 
values ‘job1’ through ‘job5’ must be valid jobnames. When you specify 
JOBNAMEP, GTF traces events for the jobs you specify. If you specify 
JOBNAMEP, but do not specify JOBNAME = before replying END, then no 
JOBNAME filtering takes place and GTF traces all jobnames. 


If you use more than one line to specify jobnames, GTF stacks your replies until 

you specify the maximum of five jobnames. If any line of your reply contains an 

error in the specification of jobnames, GTF prompts you to respecify the invalid 
- value, and leaves intact the valid stacked values from other lines of your reply. 


Note: If you specify both JOBNAMEP and ASIDP, GTF might trace jobs that | 
~ JOBNAMEP did not identify. This occurs if the address spaces that ASIDP 
_ identified contain jobs that JOBNAMEP did not identify. 


Pi = (codeO[ ,coden ]...[ ,code255 |) | 
specifies one to 256 program interruption codes (decimal notation) that you want 
traced. All other program interruptions are filtered out. If you specify PIP or. 
SYSP, and do not specify PI= in response to this prompting message, no 
program interruption filtering takes place and GTF traces all program 
interruptions. 


SSCH = (devnum1[,devnumn ]...[,devnum50 ]) 
specifies one to 50 device numbers (hexadecimal notation) for which you want 
SSCH operations traced. All other SSCH operations are filtered out. If you 
specify SSCHP or SYSP, and do not specify SSCH= in response to the 
prompting message, no SSCH filtering takes place and GTF traces all SSCH 
operations. 


SVC = (svcnum1[,svcnumn j...[,svonum50 }) 
specifies one to 50 SVC numbers (decimal notation) that you want traced. All 
other SVC numbers are filtered out. If you specify SVCP or SYSP, and do not 
specify SVC = in response to the prompting message, no SVC filtering takes 
place and GTF traces all SVC numbers. 


USR = (eventt|,eventn |...[,event50 |) 
specifies one to 50 user event identifiers (EIDs) that you want GTF to test when 
you specify TEST = YES on the GTRACE macro. When you specify TEST = YES, 
GTF tests whether or not you specified the EID in the list of EIDs that you 
selected for USRP. The values ‘event1’ through ‘event50’ are three-digit 
hexadecimal numbers from X'000' to X'FFF'. If you specify USRP and do not 
specify USR= in response to the prompting message, all executions of GTRACE 
using TEST = YES return an indication that tracing is not active. 


USRP does not limit GTF tracing to those user EIDs that you specify. The 
purpose of USRP is to cause GTF to build an internal table of EIDs that GTF uses 
when you specify TEST = YES on the GTRACE macro. 


Notes: 


GTF imposes a limit on the number of specific values you can supply through 
prompting. When you exceed this limit, GTF issues a message and you must 
respecify all values. 


You may specify one to 50 device numbers for |O= or SSCH=; you may specify 
one to 50 device numbers for |O=SSCH=. However, the sum of device 
numbers that you specify using l|O= and |O=SSCH= may not exceed 50; 
likewise the sum of device numbers that you specify using SSCH= and 
1O0=SSCH= may not exceed 50. 


The device number is not the same as the subchannel number. You must 
specify device numbers for |O=, lI|O=SSCH=, and SSCH=. 


Within a given reply, each keyword that you specify must be complete. If you 
need to specify more events for the same category, respecify the keyword ina 
subsequent reply with the additional events as follows: 


Reply #1 I0=(191,192,193) ,SVC=(1,2,3,4,5) 
Reply #2 SVC=(6,7,8,9,10) 


If you use more than one reply to specify values for the same keyword, the 
maximum number of values you can specify for that keyword does not change. 
For example: 

Repiy #1 10=(191,192,193) ,ASID=(1,C) 

Reply #2 ASID=(3,A,B) 


Although you use two replies to specify ASID=, the maximum number of ASIDs 
you can specify is still 5. | 


To ensure recording IO events for a device with multiple addresses, specify all 
addresses in the reply. 


If END is not encountered within a reply, the following message prompts for 
further specification by the user/operator: 


AHL102A CONTINUE TRACE DEFINITION OR REPLY END 


When trace option specification is complete, the operator is notified which trace 
parameters are accepted. (Message AHL103)). 


For sample prompting sequences, refer to “Example 6: Prompting Keywords 
Stored in SYS1.PARMLIB”, “Example 7: Specifying Which System Events GTF 
Traces, Using Trace Options SYSP and USRP”, and “Example 9: Specifying 
Which System Events GTF Traces, Using Trace Options SSCHP, IOP, PCI, 
CCWP, SVC, and JOBNAMEP’”. 


Prompting increases GTF storage requirements. Refer to Figure 1-7 on 
page 1-26 GIF Storage Requirements for further information. 
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GTF Examples 


Using the GTF Cataloged Procedure 


Example 1: Initialization 
You initialize GTF by starting a cataloged procedure that indicates the parmlib 
member GTFPARM. (See example 4). The trace options are specified in the 
parmlib member record. In this example, the options are TRACE =SYSM, DSP, PCI, 
SRM, TRC, USR. This example shows the messages and reply, (r), generated by the 
initial START conan: 


START GIF. EXAMPLE 

AHL1211 SYS1.PARMLIB INPUT INDICATED 

AHL103I TRACE OPTIONS SELECTED--SYSM,USR, TRC,DSP, PCI, SRM 
QQ AHL125A RESPECIFY TRACE OPTIONS OR REPLY U 

R 00,U 


AHLO311 GIF INITIALIZATION COMPLETE 


Example 2: Internal Tracking 
This example shows GTF started with MODE =iNT. The trace data is maintained in 
virtual memory and is not recorded on an external device. In this example, the 
operator overrides the trace options given in the supplied SYS1.PARMLIB member. 


START GTF.EXAMPLE2, , , (MODE=INT) ,DSN=NULLFILE 

AHL1211 SYS1.PARMLIB INPUT INDICATED 

AHL1031I TRACE OPTIONS SELECTED - SYSM,USR,TRC,DSP,PCI,SRM 
00 AHL125A RESPECIFY TRACE OPTIONS OR REPLY U 

R 00, TRACE=10,SSCH,SVC,DSP 

AHL1031 TRACE OPTIONS SELECTED -- DSP,SVC,10,SSCH 

00 AHL125A RESPECIFY TRACE OPTIONS OR REPLY U 
~R 01,U 
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Example 3: Tracing Output to an Existing Data Set on Tape 
This example shows how the START command is used to direct GTF trace output to 
an existing data set residing on tape rather than to an existing data set residing on a 
DASD. The device type and volume serial number are supplied. The disposition 
and name of the trace data set are changed from DISP = (NEW,KEEP) and 
DSNAME = SYS1.TRACE to DISP = (OLD,KEEP) and DSNAME=TPOUTPUT. The 
specified tape has a volume serial of TRCTAP and resides on a 3400 tape drive. 
Note that the GTFPARM member of SYS1.PARMLIB is used to specify the trace 
options. 


START GTF,3400, TRCTAP, (MODE=EXT) ,DISP=0LD , DSNAME=TPOUTPUT 
AHL103I TRACE OPTIONS SELECTED--SYSM,DSP,PCI,SRM,TRC,USR 
QO AHL125A RESPECIFY TRACE OPTIONS OR REPLY U 

R Q0,U 
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Example 4: Storing Trace Options in SYS1.PARMLIB 
To save time when starting GTF, first store one or more combinations of trace 
options as members in SYS1.PARMLIB, and include a SYSLIB DD statement in the 
cataloged procedure. If you do this, GTF will retrieve the trace options from 
SYS1.PARMLIB, instead of prompting you to supply them through the console. GTF 
will display the trace options for you, and then issue AHL125A, to which you reply 
‘U’ to accept the SYS1.PARMLIB options. 


This example shows the job control statements and utility control statements 
needed to add trace options to SYS1.PARMLIB using IEBUPDTE: 


//GTFPARM JOB MSGLEVEL=(1,) 

EXEC  PGM=IEBUPDTE, PARM=NEW 
//SYSPRINT DD SYSOUT=A 
//SYSUT2—ODD DSNAME=SYS1.PARMLIB,DISP=SHR 
//SYSIN DD DATA 
sf ADD  NAME=GTFA,LIST=ALL, SOURCE=0 
TRACE=SYSP,USR 


SVC=(1,2,3,4,10) , 10=(D34,DOC) , SSCH=ED8, PI=15 
| ADD NAME=GTFB, LIST=ALL, SOURCE=0 
TRACE=10,SSCH, TRC 

| ADD NAME=GTFC,LIST=ALL, SOURCE=0 
TRACE=SYS , PCI 


/* 


For full descriptions of the statements, refer to Utilities and JCL Reference. For 
further information regarding SYS1.PARMLIB, refer to Initialization and Tuning. 
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A sample SYSLIB DD statement to be included in a GTF cataloged procedure might 
look like this: - 


| //SYSLIB DD DSN=SYS1.PARMLIB(GTFA) ,DISP=SHR 


The new member name can also be specified on the START command while using 
the IBM-supplied GTF procedure, as in the following example: 


S GTF,,,(MODE=EXT, TIME=YES) ,MEMBER=GTFB | 


Example 5: Starting GTF With a User Cataloged Procedure That Does Not Have a SYSLIB 


DD Statement 
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When GIF is started with a user procedure containing no SYSLIB DD statement, the 
operator receives the following message: 


soo SPECIFY TRACE OPTIONS 


The operator must then reply with the TRACE= keyword to specify the events to be 
recorded during GTF execution. 


In the following example, a user cataloged procedure (USRPROC) is invoked to start 
GTF in external mode to a direct access data set, ABCTRC, on device 250. The 
trace options selected by the operator result in trace data being gathered for all SVC 
and IO interruptions, for all SSCH operations, for all matching SLIP traps with a 
tracing action specified or SLIP traps in DEBUG mode, and for all dispatcher events. 
Also, all issuers of the GTRACE macro will have their user data recorded in the 
trace buffers. The trace data is written into the data set ABCTRC. (Note that when 
the end of the primary extent is reached, writing continues at the beginning). 


START USRPROC ,250,333005, (MODE=EXT) ,DSN=ABCTRC 

QO AHL100A SPECIFY TRACE OPTIONS 

R 00, TRACE=SVC,SSCH,10,DSP,SLIP,USR 

AHL103I TRACE OPTIONS SELECTED--USR,DSP,SVC,10,SLIP,SSCH 
O1 AHL125A RESPECIFY TRACE OPTIONS OR REPLY U 

R Q1,U 
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Example 6: Prompting Keywords Stored in SYS1.PARMLIB 


Some GTF options cause GTF to prompt you for keywords if you specify these 
options through the system console. If the SYS1.PARMLIB member contains any of 
these options, GTF will not prompt you to enter keywords through the console; the 
prompting keywords must appear in the member’s records. A SYSLIB DD statement 
in a cataloged procedure causes the prompting keywords to be read from the 
specified SYS1.PARMLIB member. The second and subsequent logical records in 
the member should contain only those keywords for which prompting is allowed. 


Prompting input from PARMLIB is complete when either the END keyword is 
encountered, or when end-of-file is reached on the member. Each keyword must be 
complete for each prompting record. If the need arises to indicate more events for 
the same keyword, respecify the keyword in a subsequent prompting record with the 
additional events as follows: 


Record #1 TRACE=IOP,SVCP,SSCH 


Record #2 10=(D34,D0C) ,SVC=(1,2,3) 
Record #3 SVC=(4,5,6,7,8,9,10) ,END 
At this point, do not attempt to respecify the keyword through the system console, or 
you will override all of the options and keywords in the SYS1.PARMLIB member. 


When GTF finishes reading the options and prompting keywords in the 
SYS1.PARMLIB member, it displays the options through message AHL103I: 


ar evenerenrenar nner 


AHL103I TRACE OPTIONS SELECTED--SYSP,USR 
AHL103I 10=(D34,DOC) ,SSCH=(ED8) ,SVC=(1,2,3,4, 10) 


This message may be multilined depending on the number of options selected by 
the operator. If the set of devices specified for |O= and SSCH= are identical, 
message AHL1031 will show them as if specified by use of IO=SSCH. 


After GTF displays all of the options specified, it gives you the opportunity to accept 


the SYS1.PARMLIB options, or completely change the options by respecifying them 
through the console: 


AHL125A RESPECIFY TRACE OPTIONS OR REPLY U. 


Example 7: Specifying Which System Events GTF Traces, Using Trace Options SYSP and 


USRP 


In this example, the operator started GTF in external mode to the data set defined in 
the cataloged procedure. The operator selected two trace options in reply 00. SYSP 
requests that GTF trace specific system event types; USRP requests that GTF trace 
specific user entries that the GTRACE macro generates. Message AHL101A 
instructed the operator to specify values for the SVC, 10, SSCH, PI, and USR 
keywords. In reply 01, the operator selected five SVCs, two devices for 
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non-program-controlled I/O interruptions, one device for SSCH operations, and 
three user event identifiers. GTF does not record any otherSVC, 

lO, and SSCH events. Because the operator did not specify any program 
interruption codes for Pil=, GTF would trace all program interruptions. 


START MYPROC.EXAMPLE7, , , (MODE=EXT) 


QO AHL1QOA SPECIFY TRACE OPTIONS 
R 00, TRACE=SYSP,USRP 
-Q1 AHL1O1A SPECIFY TRACE EVENT KEYWORDS--I0=,SSCH=,SVC=,PI=,USR= 
1 AHL1Q1A SPECIFY TRACE EVENT KEYWORDS--10=SSCH= 
R O1,SVC=(1,2,3,4,10) , 10=(191,192) ,USR=(10,07A, AB) 
Q2 AHL102A CONTINUE TRACE DEFINITION OR REPLY END 
R 02,SSCH=282, END 
AHL1031 TRACE OPTIONS SELECTED--SYSP,PI, 10=(191, 192) ,SSCH=(282) 
AHL1031 SVC=(1,2,3,4,10) ,USR=(010,07A,OAB) 
3 AHL125A RESPECIFY TRACE OPTIONS OR REPLY U 
R 03,U 


exampe 8: Starting GTF to Trace VTAM Reniois Network Activity 
GTF can be used to trace VTAM activity only if VTAM is started with the GTF option. 
See VTAM Operations for details. In the following example, GTF options are not 
stored in SYS1.PARMLIB; the operator enters the trace options directly at the 
console. Three GTF options are required to record all VTAM traces: 


e RNIO must be specified so that the VTAM I/O trace can function for an NCP ora 
remote device attached to the NCP. 


© {0 or IOP must be specified so that the VTAM I/O trace can function for a local 
device. 


e USR must be specified so that the VTAM buffer and the NCP line traces can 
function. 


GTF must be started with the GTF START command before a trace can be activated | 
from VTAM. 


START MYPROC.EXAMPLES8, , , (MODE=EXT, TIME=YES) 
QO AHL1OOA SPECIFY TRACE OPTIONS 

R 00, TRACE=RNIO,10,USR 

AHL1031 TRACE OPTIONS SELECTED--10,USR,RNIO 
Q1 AHL125A RESPECIFY TRACE OPTIONS OR REPLY U 


R 01,U 
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Example 9: Specifying Which System Events GTF Traces, Using Trace Options SSCHP, 

IOP, PCI, CCWP, SVC, and JOBNAMEP 
In this example, the operator started GTF in external mode to the data set defined in 
the cataloged procedure. The operator selected six trace options in reply 00. 
Message AHL101A instructed the operator to specify values for the 1O, SSCH, CCW, 
and JOBNAME keywords. In reply 01 the operator selected one device for tracing 
both lO and SSCH events, limited GTF tracing to one job, and specified five options 
for CCW tracing. As a result of the operator’s specifications, GTF would trace CCWs 
for both start subchannel operations and I/O interruptions at device 580 for the job 
BACKWARD, and all SVCs in BACKWARD’s address space. GTF would allocate 200 
entries in the PCI table, and trace up to 100 CCWs, up to 40 bytes of data for each 
CCW, and the IOSB. 


START USRPROC, , , (MOD=EXT) 
00 AHL1IOOA SPECIFY TRACE OPTIONS 
R 00, TRACE=SSCHP,IOP,PCI,CCWP,SVC,JOBNAMEP 


Q1 AHLIO1A SPECIFY TRACE EVENT KEYWORDS 
~-10=, SSCH=, CCW=, JOBNAME=, I0=SSCH= 


R 01, JOBNAME=(BACKWARD) , 10=SSCH=580 

02 AHL102A CONTINUE TRACE DEFINITION OR REPLY END 

R 02,CCW=(CCWN=100, DATA=40, PCITAB=2, I0SB,SI) ,END 
AHL103I TRACE OPTIONS SELECTED--PCI,SVC, I0=SSCH=(580) 
AHL103I CCW=(SI, IOSB,CCWN=100, DATA=40, PCITAB=2) 
AHL1031 JOBNAME=(BACKWARD) 

Q3 AHL125A RESPECIFY TRACE OPTIONS OR REPLY U 


R 03,U 
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How to STOP GTF 


To stop GTF processing, you specify the STOP command and either the GTF 
identifier that you specified in the START command, or the device number of the 
GTF trace data set. See the description under “How to Specify the START 
Command” on page 1-3. If you are not sure of the identifier or device number, use 
the operator display command: 


DISPLAY ACTIVE,LIST 


This command causes the system to display the number of: 


¢ Active batch jobs 

e Active time sharing users. 

¢ Mount commands in execution 
e Started tasks, including GTF 


The LIST parameter causes the system to include jobnames and V=R region 
boundaries in the A display. | 


How to Specify the STOP Command 
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Figure 1-6 shows the general format of the STOP command that you use to stop GTF 
processing. The STOP command is similar to the START command. When you 
enter either the START or STOP command, you must enter the command from a 
master console. 


{STOP|P}{{identifier|GTF}|device number} 


Figure 1-6. General Format of the STOP Command 


The identifier on the STOP command is the same identifier that you specified on the 
START command when you started GTF. The device number on the STOP command 
is the same device number that you specified on the START command when you _ 
started GTF. If you started GTF in internal mode and did not specify an identifier, . 
the identifier is ‘GTF’. 


You may enter the STOP command at any time during GTF processing. The STOP 
command stops anything that satisfies the parameters on the STOP command. For : 
example, if you start both an external writer and GTF with the identifier 162, and 
later specify ‘STOP 162’, both the external writer and GTF stop. 


Note: If GTF does not respond to the STOP command with message AHLOO6I, then 
the STOP command is not in effect and the GTF session continues. The GTF session 
remains active in the system until the next IPL. The CANCEL and FORCE 
commands have no effect because GTF is a non-cancellable system task. However, 
you can stop GTF by using the FORCE ARM command. Refer to Operations: 

System Commands of the FORCE ARM command. 


Sample STOP Commands 


Example 1: Using the Identifier 
This example starts a GTF session with the identifier EXAMPLE and with trace data 
maintained in the GTF address space. The DSN keyword is entered to prevent 
allocation of an external trace data set as specified in the cataloged procedure. 


START GTF.EXAMPLE, ,, (MODE=INT) ,DSN=NULLFILE 


This command would stop the GTF session started in the previous example: 


STOP EXAMPLE 7 


Example 2: Using the Device Number 
This example starts a GTF session with trace data recorded on the non-labeled tape 
on device 282. Each trace record will be timestamped. Twenty kilobytes of GTF 
data will be formatted if an SVC dump is taken. 


START GTF,282,, (TIME=YES , SDUMP=20K) , LABEL=(, NL) | 


This command would stop the GTF session started in the previous example: 


STOP 282 | 


Example 3: When You Must Display Active Jobs 
This example starts a GTF session with trace data recorded on an external device. 
Since it is not apparent which is the GTF recording device, you have to display 
active jobs with the D A,LIST command before you can stop GTF. The GTF session 
started in this example could run in an address space of a maximum of 1000K. 


START GTF,,,(MODE=EXT) ,REGION=1000K 
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GTF Storage Requirements 


Extended Pageable Link Pack Area | System Queue Area ) 


Region Storage 


SUBPOOL: GTF uses 4-16K in subpools 5 and 6 for 


Fix = Opt + Prmpt + 8K SQA = 16500 + ce +SAVE + CBLOC 
; . : ontrol blocks; this area is fixed while 
is active. , , 


REG: 232 bytes per processor are required for. 
register save areas, regardless of whether 
or not GTF is active. 


REGION: GTF requires a minimum of an 800K 
virtual region to execute. Also,ifGTF 
must hold large amounts of trace data in 
its address space, it can use a maximum of 
750 pages in the page data set. To acquire 
this space you specify the REGION= 
parameter on an EXEC card or START 
command with one of the following values: 


1) G+708K (only if BUF = specifies a 
value of 57 or defaults.) 


Opt: Sum of storage required for each GTF option 
specified. See the table below to calculate OPT. 


Prmpt: Optional additional 1.5K if any prompting 
options specified. 


8K: 8K required for services. | SAVE: 1352 bytes per processor are required — 
7 for save/work areas when GTF is active. 


[Option sd 
SYSM FAK CBLOC: 1700-2200 bytes are needed for control 


| SYS with DSP and/or SRM a blocks when GTF is active. 
and/or RNIO 7K Notes: . 


SYS, SYSP 1. When you specify PCI and either CCW or CCWP, 2) G + 1400K 
Pi, DSP, PIP GTF requires the following additional SQA 3) G + 2080K 
storage: 4) G +2770K 


110, lOP, SIO, SIOP, SSCH, 
SSCHP 


SVC, SVCP 
SRM, RR, RNIO 


[Pcr, TRC [ No Requirement _ 
Lccw,ccwP CUT CK 


Notes: 

1. When you specify more than one event from aline, fhe. 
size requirement is the same as if you specified only 
one option i.e., DSP and PI require 2.5K. 

2. For the maximum storage requirement round up the 
storage requirement for each option you specified, 
to the nearest 4K boundary. 

3. For the minimum storage requirement, round up the 
‘FIX' value to the nearest 4K boundary. 


16 + 1200 * (value of PCITAB in bytes) 

2. When you specify either CCW or CCWP, GTF 
uses 4096 additional bytes of the SOA for each 
processor. 


3. When you specify USRP, GTF uses 4096. 
additional bytes of the SQA for each processor. 


G: The amount of address space 
required for the maximum size 
combination GTF and BSAM. 


Note: 
Coding a large REGION size does not mean that GTF 
will use the maximum available address space. The 
space is used as long as it is necessary to hold trace 
data, and then when the trace data is moved into trace 
data set the space is freed: GTF drops to its normal 
requirement; G+ 40K or G/4K + 10 pages. 


Extended System Queue Area 


ESQA =N 


4096 times the number of blocks specified 
on the BLOK = keyword parameter of the 
GTF START command. 


The default is 40960 bytes. 


Example — 
1) Options = |OP, SSCHP, SVC 
Fix = 10.5 + 1.5 + 8 = 20K minimum or 
= 124+1.5+8= 21.5 = 24K maximum 
2) Options = SYSM, SRM, USR, TRC 
Fix = 8.5+0+ 8K = 16.5 = 20K minimum or 
=12+0+ 8K = 20K maximum 


Figure 1-7. GTF Storage Requirements 


User Trace Data Created With GTRACE 


lf you want your own trace data to be recorded in the GTF trace buffers, you can use 
the GTRACE macro instruction to define the data. In one invocation of GTRACE, an 
application program can record up to 256 bytes of data in a GTF trace buffer. The 
number of bytes of data in the data field of the GTF trace record is equal to the 
number of bytes of data that you specify plus 12 bytes. The additional 12 bytes are 
the GTRACE header, which consists of a 4-byte ASCB address followed by an 8-byte 
jobname. 


GTRACE is effective only when GTF is active and is accepting user data -- that is 
when GTF was started with at least TRACE = USR specified. 


For information on coding the GTRACE macro instruction, see SPL: Application 
Development Macro Reference. 


EID Assignment for User Events 
Events traced by the GTRACE macro will use an event identifier (EID) from one of 
the three ranges listed below: 


0000-1023 user events 
1024-1535 | reserved for program products | 
1536-4095 reserved for BM components and subsystems 


EIDs in the first range are available for general use by all GTF users. EIDs in the 
second and third ranges are reserved. 


How to Print User Data 
Like other trace data, information recorded by the GTRACE macro can be printed 
using IPCS. Also, IPCS allows the writing of user exits to format specific types of 
data records. For information on writing IPCS user exits, see /PCS Planning and 
Customization. 
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GTF Error Recovery Handling 


GTF Output 
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GTF recognizes all errors that occur while building a trace record as potentially 
recoverable. Whether or not recovery is attempted depends on what moe specify in 
the START command. 


If you specify DEBUG= YES, GTF does not attempt error recovery. It issues an error 
message and then terminates, so that the contents of the GTF buffers immediately 
prior to the error are preserved. 


If you specify DEBUG=NO, GTF initiates the following error procedures: 


¢ For minor errors in the routine that builds the trace record (the build routine), 
GTF flags the field in the trace record that led to the error and continues 
processing. GTF does not issue a message to the operator’s console, nor does 
GTF disable the function that caused the error. Instead, GTF proceeds as if no 
error had occurred. 


e For severe errors in the build routine, GTF flags the entire record that was being | 
built, issues a message to the console, suppresses the error and continues 
processing without the function that caused the error. 


¢ For errors in the routine that filters trace events, GTF suppresses filtering for | 
future events of the same type, issues a message to the console, and continues _ 
_ processing, gathering all events of the type that encountered the error. 


Errors that occur outside the build and filter routines are not recoverable; they 
result in immediate abnormal termination of GTF. 


Note: The termination of GTF does not cause termination of a user’s task. 


GTF creates two kinds of records: trace records and control records. For 
information about the format of trace records prior to GTF. Eeeo rene: refer to Using 
Dumps and Traces. 
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Introduction 


LIST is a service aid that operates as a problem program. It produces several kinds 
of output that you need to perform certain diagnostic functions; these functions are 
described below: 


Verifying an object module. LIST produces a formatted listing that contains the 
external symbol dictionary (ESD), the relocation dictionary (RLD), the text of the 
program containing instructions and data, and the END record. 


Mapping CSECTs in a load module. LIST produces a listing of the load module 
along with its module map and cross-reference listing, which you can examine to 
determine the organization of CSECTs within the load module, the overlay structure, 
and the cross-references for each CSECT. 


Verifying the contents of the nucleus. LIST can produce a map and cross-reference 
listing of a nucleus. The map no longer represents the IPL version of the nucleus 
and message AMB129l is issued. Use IPCS to format a NUCMAP. For information 


on using IPCS see /PCS User’s Guide. 


Tracing modifications to the executable code in a CSECT. LIST produces a 
formatted listing of all information in a load module’s CSECT identification records 
(IDRs). An IDR provides the following information: 


e It identifies the version and modification level of the language translator and the 
date that each CSECT was translated. (Translation data is available only for 
CSECTs that were produced by a translator that supports IDR generation.) 


e lt identifies the version and modification level of the linkage editor that built the 
load module and gives the date the load module was created. 


e Itidentifies, by date, modifications to the load module that may have been 
performed by SPZAP. 


An IDR may also contain optional user-supplied data associated with the executable 
code of the CSECTs. 


Mapping the link pack area. LIST produces a map of all modules in the fixed link 
pack area, the modified link pack area, and the pageable link pack area. 


Note: Any load module to be formatted and printed by AMBLIST must have the 
same format as those created by the linkage editor. 
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2-2 Service Aids 


The minimum partition or region for executing of AMBLIST is 64K for all functions 
except LISTLPA, which requires 100K. 


LIST requires the following JCL statements: 


JOB Statement 
initiates the job. 


EXEC Statement 
calls for the execution of AMBLIST. 


SYSPRINT DD Statement 
defines the message data set. 


anyname DD Statement 
defines an input data set. This statement cannot define a concatenated data set. 


SYSIN DD Statement 
defines the data set (in the input stream) that contains LIST control statements. 


Control Statements 


You control LIST processing by supplying control statements in the input stream. 
You must code the control statements according to the following rules: 


e Leave column 1 blank, unless you want to supply an optional symbolic name. A 
symbolic name must be terminated by one or more blanks. 


e lf acomplete control statement will not fit on a single card, end the first card 
with a comma or a non-blank character in column 72 and continue on the next 
card. Begin all continuation cards in columns 2 - 16. You must not split 
parameters between two cards; the only exception is the MEMBER parameters, 
which may be split at any internal comma. 


The control statements and their parameters are: 


LISTLOAD [OUTPUT={MODLIST | XREF|BOTH}][,TITLE=('title' ,position) ] 


[ ,DDN=ddname] [ ,MEMBER={member| (member1,membern...) }] 


[ ,RELOC=hhhhhh] 


OUTPUT = {MODLIST|XREF|BOTH} 
specifies the type of load module listing to be produced. OUTPUT = MODLIST 
requests a formatted listing of the control and text records of a load module, 
including its external symbol dictionary and relocation dictionary records. | 
OUTPUT = XREF requests a module map and cross-reference listing for the load 
module. OUTPUT = BOTH requests both a formatted listing of the load module 
and its map and cross-references. If this parameter is omitted, OUTPUT = BOTH 
will be assumed. 


TITLE = ('title' ,position) 
specifies a title, from one to forty characters long, to be printed below the 
heading line on each page of output. (The heading line identifies the page 
number and the type of listing being printed, and is not subject to user control.) 
The position subparameter specifies whether or not the title should be indented; 
if TITLE =('title',1) is specified, or if the position parameter is omitted, the title 
will be printed flush left, that is, starting in the first column. If you want the title 
indented from the margin, use the position parameter to specify the number of 
characters that should be left blank before the title. If you specify a position 
greater than 80, the indentation from the margin defaults to 1. 


Note: Do not punctuate your title with commas; since LIST recognizes a comma 
as a delimiter, anything that follows an embedded comma in a title will be 
ignored. 


DDN = ddname 
identifies the DD statement that defines the data set containing the input 
module. If the DDN= parameter is omitted, LIST will assume SYSLIB as the 
default ddname. 


MEMBER = {member|(member1,membern...)} | 
identifies the input load module by member name or alias name. To specify 
more than one load module, enclose the list of names in parentheses and | 
separate the names with commas. If you omit the MEMBER= parameter, LIST 
will print all modules in the data set. | 
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2-4 Service Aids 


RELOC = hhhhhh 
specifies a relocation or base address in hexadecimal of up to eight characters. 
When the relocation address is added to each relative map and cross-reference 
address, it gives the absolute main storage address for each item on the output 
listing. If you omit the RELOC= parameter, no relocation is performed. 


LISTOBJ [TITLE=(‘'title',position) ][, DDN=ddname | 
[ ,MEMBER={member | (member1,membern...)}] 


TITLE = (‘title' ,position) 
specifies a title, from one to forty characters long, to be printed below the 
heading line on each page of output. (The heading line identifies the page 
number and the type of listing being printed, and is not subject to user control.) 
The position parameter specifies whether or not the title should be indented; if 
TITLE = ('title',1) is specified, or if the position parameter is omitted, the title 
will be printed flush left, that is, starting in the first column. If you want the title 
indented from the margin, use the position parameter to specify the number of 
characters that should be left blank before the title. If you specify a position 
greater than 80, the indentation from the margin defaults to 1. 


Note: Do not punctuate your title with commas; since LIST recognizes a comma | 
as a delimiter, anything that follows an embedded comma in a title will be 
ignored. 


DDN = ddname 
identifies the DD statement that defines the data set containing the input 
module. If the DDN= parameter is omitted, LIST will assume SYSLIB as the 
default ddname. | 


MEMBER = {member|(member1|[,membern |...)} 
identifies the input object module by member name or alias name. To specify 
more than one object module, enclose the list of names in parentheses and 
separate the names with commas. CAUTION: You must include the MEMBER= | 
parameter if the input object modules exist as members in a partitioned data set 
(PDS or PDSE). If you do not include the MEMBER= parameter, LIST will 
assume that the input data set is organized sequentially and that it contains a 
single, continuous object module. 


ERROR 4 MORN 


LISTIDR [OUTPUT={IDENTIALL}I[,TITLE=('title' ,position) | 
[ ,DDN=ddname]| [,MEMBER={member | (member1,membern...)}] 


[ ,MODLIB] 


OUTPUT = {IDENT|ALL! 
specifies whether LIST should print all CSECT identification records or only 
those containing AMASPZAP data and user data. If you specify OUTPUT = ALL, 
all IDRs associated with the module will be printed. If you specify 
OUTPUT =IDENT, LIST will print only those IDRs that contain SPZAP data or 
user-supplied data. If you omit this parameter, LIST will assume a default of 
OUTPUT=ALL. Do not specify OUTPUT if you specify the MODLIB parameter. 


TITLE = (‘title' position) 
specifies a title, from one to forty characters long, to be printed below the 
heading line on each page of output. (The heading line identifies the page 
number and the type of listing being printed, and is not subject to user control.) 
The position parameter specifies whether or not the title should be indented; if 
TITLE = ('title',1) is specified, or if the position parameter is omitted, the title is 
printed flush left, that is, starting in the first column. If you want the title 
indented from the margin, use the position parameter to specify the number of 
characters that should be left blank before the title. If a position greater than 80 
is specified, the indentation from the margin defaults to 1. 


Note: Do not punctuate your title with commas; since LIST recognizes a comma 
as a delimiter, anything that follows an embedded comma in a title will be 
ignored. If the MODLIB parameter is specified, do not indicate a TITLE because 
it will be ignored. 


DDN = ddname 
identifies the DD statement that defines the data set containing the input 
module. If you omit the DDN= parameter, LIST will assume SYSLIB as the 
default ddname. 


MEMBER = {member|(memberi,membern...)} 
identifies the input load module by member name or alias name. To specify 
more than one load module, enclose the list of names in parentheses and 
separate the names with commas. If you omit the MEMBER= parameter, LIST 
will print all modules in the data set. Do not specify MEMBER if you specify the 
MODLIB parameter. 


MODLIB 
prevents LIST from printing the module summary. LIST prints the IDRs that 
contain SPZAP data or user-supplied data. No page ejects occur between 
modules. When you specify MODLIB, the TITLE= parameter is ignored, and the 
OUTPUT = or MEMBER= parameters are not valid parameters. 


LISTLPA [FLPA][,MLPA][,PLPA] 


LISTLPA 
lists the modules in the fixed link pack area, the modified link pack area, and the 
pageable link pack area. The map includes modules residing in the extended 
sections of each link pack area. If you do not specify any parameters on the 
LISTLPA control statement, then LIST maps modules from ail three link pack 
areas. 


Note: LIST reflects only the system currently operating. 


FLPA 
requests mapping of the modules in the fixed link pack area. 


MLPA 
requests mapping of the modules in the modified link pack area. 


PLPA 
requests mapping of the modules in the pageable link pack area. 
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 QOutput 


LIST produces a separate listing for each control statement that you specify. The 
first page of each listing always shows the control statement as you entered it. The 
second page of the listing is a module summary, unless you requested LISTOBu, 
LISTLPA, or MODLIB with LISTIDR; in that case, no module summary will be 
produced, and the second page of the listing will be the beginning of the formatted 
output. : | 

The module summary gives the member name (with aliases), the entry point, the 
linkage editor attributes, and system status index information (SSI) for the module 
being formatted. Figure 2-1 shows a typical module summary. Note that the 
linkage editor attributes are not represented by a bit map. 


eee MODULE SUMMARY. ***ee 


MEMBER NAME  IGC0002I MAIN ENTRY POINT 000000 AMODE OF MAIN ENTRY POINT 31 


** ALIASES ** ALIAS ENTRY POINT AMODE OF ALIAS ENTRY POINT 


IGGO29ER 0042F0 31 
TGGO290A — 0011F0 31 
TGGO30CM 000948 31 
IGGO300F 0047B0 31 


***%* LINKAGE EDITOR ATTRIBUTES OF MODULE **** 


** BIT STATUS BIT STATUS — BIT STATUS BIT STATUS ** 
Q NOT-RENT © 1 NOT-REUS 2 NOT-OVLY 3. NOT-TEST 
4 = NOT-OL 5 BLOCK | 6 EXEC _ 7 MULTI-RCD 
8 NOT-DC 9 ZERO | 10 EP-ZERO 11 RLD 
12 EDIT | 13 NO-SYMS | 14 F-LEVEL 15 NOT-REFR 


MODULE SSI: NONE ~ 
APFCODE 00000000 
RMODE ANY 


*****_L OAD MODULE PROCESSED BY VS LINKAGE EDITOR 


Figure 2-1. Sample Module Summary of LISTLOAD 


2-6 Service Aids 


The third page of the listing (or, for LISTOBJ, LISTLPA, or MODLIB with LISTIDR the 
second page) is the beginning of the formatted output itself. 


For LISTLOAD, the formatted output consists of the load module, or the module map 
and cross-reference listing, or both. Figure 2-2 on page 2-8 shows an example of 


-LISTLOAD module map output. Figure 2-3 on page 2-10 shows an example of the 


cross-reference listing for the same module. 


For LISTOBJ, the body of the listing consists of the object module listing, the 
module’s external symbol dictionary, and its relocation dictionary. Figure 2-4 on 
page 2-12 shows an example of LISTOBJ output. 


For LISTIDR, the third page of the listing begins a complete list of all CSECT 
identification records for the module. Figure 2-5 on page 2-13 shows an example of 
LISTIDR output. 


For LISTLPA, the second page of the listing is a map of the link pack area, with 


modules ordered alphabetically by name. Figure 2-6 on page 2-14 shows an 
example of LISTLPA output. 
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PAGE 0001 


LISTING OF LOAD MODULE PL1LOAD 


RECORD# 1 TYPE 20 ~ CESD ESDID 1 ESD SIZE 240 
(HEX) 
4B6 


260 


TYPE ID/LENGTH(DEC) 
00(SD) 
00(SD) 
06(PR) 
02¢ER) 
02¢(ER) 
06 (PR) 
06(PR) 
00(SD) 
00(SD) 
02(ER) 
06(PR) 
06 (PR) 
06(PR) 
06 (PR) 
06(PR) 


ADDRESS SEGNUM 
000000 1 1206 
000488 1 608 
000000 a.) 
000000 : 

000000 
000004 
000008 
000718 
000720 
000000 
00000Cc 
000010 
000014 
000018 
00001C 


# SYMBOL 
PLITCO2 
PL1ITCO2A 
IHEQINV 
IHESADA 
IHESADB 
THECERR 
THEQTIC 
IHEMAIN 
THENTRY 

10 IHESAPC 

11 ITHEQLWF 

12 IHEQSLA 

13 THEQLWO 

14 PLiTCO2B 

15 PL1ITCO2C 


CES 


WON aowlwrro 


= 
N&fSe 


f&eeecet 


RECORD# 2 TYPE 20 - CESD ESDID 16 ESD SIZE 240 


SYMBOL TYPE SEGNUM ID/LENGTH(DEC) (HEX) 


RECORD# 3 


RECORD®# 4 


RECORD# 5 


CESD# 


16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 


ITHELDOA 
IHELDOB 
IHEIOBT 
IHEIOBC 
IHESAFA 
IHESAFB 
AA 

Cc 

B 

A 
IHESPRT 
IHEQSPR 
THEDNC 
IHEVPF 
IHEDMA 


TYPE 20 - CESD 


CESD# 


31 
32 
33 


34 


SYMBOL 
LHEVPB 
IHEVSC 
IHEUPA 
THEVQC 


02 (ER) 
O2(ER) 
02(ER) 
02(ER) 
02(ER) 
O2¢ER) 
02(ER) 
00¢SD) 
00 (SD) 
00(SD) 
00(SD) 
Oo (PR) 
02 (ER) 
02¢ER) 
02¢ER) 


ADDRESS 


000000 
000000 
000000 
000000 
000000 
000000 
000000 
000730 
000738 
"000740 
VOO74B 
000020 
000000 
000000 
000000 


ESDID 31 


TYPE 
O2(ER) 
02(ER) 
02(ER) 
02(ER) 


TYPE 01 - CONTROL 


CESD# 


000000 
000020 
000040 
000060 
000080 
0000A0 
0000c0 
0000E0 
000100 
000120 
000140 
000160 
000180 
0001A0 
0001C0 
0001E0 
000200 
000220 
000240 
000260 
000280 
0002A0 
0002C0 
0002E0 
000300 
000320 
000340 
000360 
000380 
0003A0 
0003c0 
0003E0 
000400 
000820 
000440 
000460 
000480 
0004A0 
0004C0 
OOO4EO 


O4BS 
0260 
0008 
0010 
0008 
0008 
0008 
0038 


Q7FOFO1S4 
58F0B020 
F811bD090 
DOAEB1 34 
Dp09241A0 
BOSSOSEF 
4002FA20 
7O00F821 
D0634150 
5880B070 
F9118000 
OSEF4110 
DO0A85080 
BOYOOSEF 
A13E9280 
po94D090 
4110B0A0 
58F0B058 
OSEF9213 
000000D0 
9201D084 
9209D063 
45E0A016 
A0000700 
D207D0A8 
920CD063 
D0937002 
DO9810FE 
possp201 
OSEF920D 
D0938003 
DO098D090 
47FOA106 
D09058F0 
12224770 
D00447FO 
§87C0014 
583c0010 
000024B8 
00000434 


Figure 2-2 (Part 1 of 2). 


2-8 = Service Aids 


LENGTH 


O7DID3F1 
OSEFOSAO 
B132F810 
F811D030 
A9600700 


9203D063° 


D093B1i11 
D0937002 
DOAES050 
D2038000 
D0904770 
B14058F0 
D0984180 
D205D0B2 
D090D202 
D600D094 
4120B183 
OSEF9213 
D06358F0 
9O0EBDOOC 
58E01000 
41A0A088 
9202D084 
S7FOFOOC 
10009200 
5880D0A0 
9502D084 
54E0B078 
8000D091 
D063920E 
FB22D093 
YFEODO98 
3880D088 
BO6005EF 
F03c59DC 
F0225020 
D2033050 
5030D004 
000034B8 
00000434 


ADDRESS 


000000 
000000 
000000 
000000 


LISTING OF LOAD MODULE PL1LOAD 


CONTROL SIZE 32 


E3C3F0F2 
4190D0B8 
DO092B080 
B13CF810 
92030063 
58F0B058 
5870B06C 
FA20D093 
DO0944150 
DO909207 
AOC8F9I11 
BOSOOSEF 
DOB25080 
DO0909211 
DO91D0B5 
DO0919180 
S8F0B054 
D0634110 
BOS805EF 
18AF41E0 
50E0D088 
07F80700 
D207D0A0 
03C1C3F2 
DOAC58E0 
F821D090 
4780A062 
9OEFDO98 
D2018002 
D0635880 
70039502 
LOFES4EO 
D2018000 
920FD063 
00104770 
DO0898EB 
70504140 
50DC0010 
00004488 
00000000 


SEGNUM 


ESD SIZE 64 


ID/LENGTH (DEC) 


TEXT 


000000D8 
50DC0018 
FA11D092 
DO92B080 
4110B174 
OSEF9204 
D2017000 
B10OF5860 
DO0905050 
DO63F811 
8002D092 
9208D063 
DO09C4180 
D063D202 
F921D091 
D0944780 
OS5EF4110 
B15058F0 
9214D063 
A0 285830 
4580A03A 
47FOFOOC 
10009200 
00000258 
100850E0 
80005870 
9503D084 
964ED098 
DO9447F0 
DOASF8 22 
D08484780 
BO7890EF 
D091D201 
58FOB02C 
FO3C58D0 
DOOCOTFE 
4001504C 
5020D008 
00005458 
89300008 


00000488 
92000062 
B130F821 
FA11D092 
58FOBO5C 
D0635880 
DO91D201 
BO068D201 
D0989680 
DO090B10C 
4780A0EE 
58F0B058 
DO0305080 
DO90D0B2 
BOCF9200 
A19E9212 
DOB24120 
BOSCOSEF 
58F0B030 
B0381522 
O7FA0SAO 
03C1C3F1 
DOAU58E0 
9O0EBDOOC 
D0884580 
DOAGFA21 
4780A076 
2B006A00 
A0805880 
DO0908000 
AOE89503 
DO98964E 
8002D094 
OSEFFO14 
bo004&50DCc 
58F0B030 
00005040 
5020D060 
000064B8 
00000648 


S90EBDOOC 
9201D063 
DOA8D090 
B1I3AF821 
O5EF4110 
BO70F821 
7002D094 
6000D091 
D0984110 
F810D092 
9208D063 
OSEF9208 
DO0A09680 
F921D090 
DO0914780 
D0634110 
B18758F0 
4110B084 
OSEF47F0 
50203050 
4190D0B0 
00000258 
100850E0 
58A0F008 
AO 3A47F0 
D0907000 
5860D088 
D0987000 
p088D205 
5870D0AC 
DO0844780 
D098 2B00 
47FOA106 
9180D001 
00109180 
O7FF584C 
30549200 
O7FEICKY 
00007488 
41660001 


(HEX) 


CCW 06000000 40000780 


58BOF010 
92C0D000 
F821D0AB 
DOB2D090 
B1144120 
D0908000 
9205D063 
D2016002 
DO09458FO 
BOB0FA11 
4110B168 
D06392190 
DOA04110 
B0D19200 
A1569280 
BiSC58FO 
BOSYOSEF 
4120B183 
47FOFO0C 
58F0B02C 
so0pc00ic 
9OEBDO0C 
D0884&580 
4SE0A016 
A0860700 
F821D093 
F872D098 
600047F0 
8000D090 
FB22D090 
AOFCS860 
6A00D098 
5880D088 
4780F03C 
D0004710 
00001244 
304C5030 
00001000 
00000000 
000002E4 


Sample LISTLOAD Output Load-Module Map 


S800F00C 
9202D063 
D092D203 
F821D0B5 
B18358F0 
F821D093 
F821D090 
D0949206 
BO6405EF 
DO92B10A 
58F0B05C 
D0634180 
D09858F0 
D0904780 
D091D200 
BOSCOSEF 
9212D063 
58F0B054 
03C1E7F1i 
4TFOFO62 
9200D062 
S8A0F008 
A03A47F0 
9203D084 
920BD063 
8002FA21 
DOSOUFEO 
A0805880 
58FOB060 
TOO00F822 
DO88F872 
70006000 
D2058000 
5820D050 
F03258D0 
47BOFO56 
D00818D3 
000014B8 
00000000 
ON0COZAC 


PAGE 0002 


RECORD# 6 


RECORD# 7 


000500 
000520 
000540 
000560 
000580 
0005A0 
0005c0 
0005E0 
000600 
000620 
000640 
000660 
000680 
0006A0 
0006C0 
0006E0 
000700 
000720 
000740 
000760 


00000258 


‘00000730 


00140014 
4OCSD9D9 
40C1C440 
E3C5C440 
o00co4u1c 
E3C5D9C5 
00000740 
00000748 
04800620 
900647F0 
00033BC8 
80109206 
804048D0 
00224820 
NTFO808A 
S8FOF008 
003CCOKC 
OVE2ZE8E2 


TYPE 02 - RLD 


R-PTR P-PTR 


2 
14 
15 

1 
12 

3 
13 


3 
12 
2 


1 


Re ee 


2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 


TYPE OE - RLD 


R-PTR P-PTR 


24 
25 
26 
2 
25 
2 
26 
1 
2 
26 
1 
2 
26 
1 
2 
26 
1 
2 
1 
10 
27 


BCVWVONNNNNNNNHNNNNNNNNN LY 


N 


00000000 
00000738 
¥ODID3F1 
D6D9I6BCS 
C9E24002 
C140CIE2 
018C0C 2c 
c440000Cc 
80000638 
0000016c 
41090008 
8206D2AF 
00480A0A 
70104150 
900447F0 
BO7A4 BDO 
SADOBO86 
07FFO000 
D2071024 
D7D9CIDS 


ADDR 
000010 
O0002E 
00029A 
0002B4 
000448 
000478 
000482 
000490 
Q0004A2 
0004BC 
0004D4 
0004D8 
0004DC 
0004E0 
OOO04FO 
OOO4uUFS 
000508 
00050c 
000510 
000514 
OO04ES8 
000518 
00051Cc 
000520 


FL ADDR 
Oc 000524 
Oc 000528 
oc 00052Cc 
09 00053D 
Oc 000600 
08 000605 
Oc 000608 
oc 00060C 
08 000611 
Oc 000614 
oc 000618 
08 00061D 
0c 000620 
Oc 000624 
08 000629 
oc 00062C 
oc 000630 
08 000635 
oc 000718 
8c 000728 
24 000748 


@S¢OCCEND OF LOAD MODULE LISTING 


LISTING OF LOAD MODULE PL1LOAD 


00000000 
00000740 
E3C3FO0F2 
E7TD7C5C3 
0c040Cc00 
GOFIFS4E 
0c1¢0000 
G40cosoc 
00000748 
80000534 
c08000D0 
4000C000 
05804860 
A05818C6 
80581B22 
B0864740 
SADOBOB4 
00000000 
00201002 
E3000000 


FL ADDR 


00000000 
00000748 
6060C3D6 
E3c5c44u0 
00000594 
F4UF1C940 
000005D4 
000c006C 
00000242 
00000748 
1¢021AC1 
1BFFSOFD 
BO8050E7 
41D000 20 
8D200008 
807A1BCC 
06208920 
50070034 
00000000 
00000000 


FL ADDR 


0002EC 
000454 


OOO4AA 


0004Cc0 


OOOUES 


QO0O4FC | 


LISTING OF LOAD MODULE PL1LOAD 


FL ADDR 


09 000559 09 00058D 09 0005CD 


FL ADDR 


OD 0004C4 


00000000 
80000000 
D4D7D3C5 
cic44oc9 
002C002C 
C2EWE340 
00120012 
000c020C 
80000534 
OOO000A4 
95043008 
00101817 
00309180 
1CCC1AD5 
41100001 
4810BO7E 
00081AD2 
063c004C 
00000004 
00000000 


00000000 
00000001 
E3C5C440 
E240F4FO 
4OCSD9D9 
C140C9E2 
QODTD3F1 
010c001Cc 
00000748 
80000534 
47808200 
41000038 
90064780 
50D70014 
19128C20 
1DC11AD2 
410D0000 
001058F0 
00000000 
00000000 


RLD SIZE 236 


FL ADDR 


0D 0004C8 


0D 000500 0c 000504 


RLD SIZE 188 


FL ADDR 


OD 0005F8 


00000000: 
0€020000 
00000560 
YEF2F0C9 
D6D96BC5 
4op9C5C1 
E3C3FOF2 
0000058c 
0000021iCc 
8903802c 
D2AFC000 
OA0A98EC 
80189205 
184D9505 
00084780 
89D00008 
00000000 
003C004KC 
00000000 
00000000 


Fl, ADDR FL 


GD 0004CC OD 


FL ADDR FL 


Figure 2-2 (Part 2 of 2). Sample LISTLOAD Output Load-Module Map 


00000000 
00000544 
00270027 
HOC2E4E3 
E7D7C5C3 
D3D3E840 
6060C5D5 
00000635 
80000534 
8A060089 
40009680 
DOOCO7FE 
701047F0 
70104770 
809648D7 
41DCD001 
STFOSOSE 


58070034. 


00000000 
00000000 


N 


ADDR 


0004D0 


ADDR 


Oc 0005FC 


PAGE 0003 


PAGE 0004 
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NUMERICAL MAP AND CROSS-REFERENCE LIST OF LOAD MODULE PLILOAD 


CONTROL SECTION 


LMOD LOC 


00 
4BB8 
718 
720 
730 
738 
740 


LMOD LOC CSECT LOC 


10 
4&D8 
ape 
4EO 
4EG 
4ES 
4F8 
WFC 
500 
504 
508 
50c 
510 
514 
518 
51c 
520 
524 
528 
52C 
600 
608 
60C 
614 
618 
620 
624 
62C 
630 
718 
728 


10 
20 


00 
08 


LENGTH OF LOAD MODULE 780 


NAME 


PLITCO2 
PLITCO2A 
IHEMAIN 
IHENTRY 
Cc 

B 

A 
IHESPRT 


IN CSECT 


PLITCO2 

PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PL1TCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLAITCO2A 
PLITCOZA 
PLiTCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 


‘PLITCO2A 


PLITCO2A 
PLITCO2A 
PL1TCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
IHEMAIN 

LHENTRY 


LENGTH TYPE 


4B6 
260 
04 
0c 
04 
04 
Ou 


REFERS TO SYMBOL AT LMOD LOC CSECT LOC 


PL1TCO2A 
ITHESADA 
IHESADB 
PLITCO2 
PL1ITCO02 
IHESAFA 
PLITCO2 
PLITCO2 
PLITCO2 
PLiTCO2 
LTHELDOA 
IHELDOB 
THELOBT 
THEIOBC 
IHESAFE 
AA 

Cc 

B 

A 
ITHESPRT 
A 
IHESPRT 
PL1TCO2 
IHESPRT 
PLITCO2 
IHESPRT 
PLITCO2 
IHESPRT 
PLiTCO2 
PL1TCO2 
IHESAPC 


NUMERICAL MAP AND CROSS-REFERENCE 


PSEUDO REGISTER 


VECTOR LOC 


00 


LENGTH OF PSEUDO REGISTERS 


NAME 


LTHEQINV 
IHEQERR 
IhEQTIC 
IHEQLWF 
IHEQSLA 
IHEQLWO 
PL1ITCO2B 
PLITCO2C 
IHEQSPR 


24 


LENGTH 


fer ecef&ee eet 


ENTRY 


LMOD LOC CSECT LOC 


4B8 


00 
00 


00 
00 
a0 
00 


00 


00 
00 


00 
00 
00 
00 


LIstT OF LOAD MODULE PLILOAD 


IN CSECT 


PLITCO2A 
SUNRESOLVED 
SUNRESOLVED 

PLITCO2 

PL1TCO2 
SUNRESOLVED 

PL1TCO2 

PL1TCO2 

PL1ITCO2 

PL1TCO2 
$UNRESOLVED 
§ UNRESOLVED 
SUNRESOLVED 
$5 UNRESOLVED 
5 UNRESOLVED 
$ UNRESOLVED 

c 

B 

A, 

IHESPRT 

A 

IHESPRT 

PLITCO2 

IHESPRT 

PL1TCO2 

IHESPRT 

PLITCO2 

IHESPRT 

PLITCO2 

PLITCO2 
$UNRESOLVED 


Figure 2-3 (Part 1 of 2). Sample LISTLOAD Output - Cross-Reference Listing 
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PAGE 0001 | 


PAGE 0002 


, aS 


CONTROL, 


NAME 


IHEMAIN 
IHENTRY 
IHESPRT 
PLiTCO2 
PL1TCO2A 


SECTION 


LMOD Loc 


740 
738 
730 
718 
720 


PSEUDO REGISTER 


SYMBOL 


A 

A 

AA 

B 

Cc 
ITHELOBC 
IHEIOBT 
ITHELDOA 
IHELDOB 
IHESADA 
THESADB 
ITHESAFA 
IHESAFB 
THESAPC 
IHESPRT 
ITHESPRT 
IHESPRT 
IHESPRT 
LHESPRT 
PL1ITCO2 
PLITCO2 
PL1ITCO2 
PLITCO2 
PL1ITCO2 
PL1ITCO2 
PL1ITCQ2 
PLITCO2 
PL1TC02 
PL1TCO2 
PL1TCO02 
PLITCO2A 


p eeeeESEND OF 


Figure 2-3 (Part 2 of 2). Sample LISTLOAD Output - Cross-Reference Listing 


NAME 


IHEQERR 
IHEQINV 
IHEQLWF 
IHEQLWO 
THEQSLA 
IHEQSPR 
IHEQTIC 
PL1TCO 2B 
PLITCO2C 


AT LMOD LOC 


740 
740 


738 
730 


VECTOR LOC 


ALPHABETICAL MAP OF LOAD MODULE PL1LOAD 


LENGTH TYPE 


04 


LENGTH 


Fefrferrreet 


ENTRY 


NAME LMOD LOC CSECT LOC CSECT NAME 


ALPHABETICAL CROSS-REFERENCE LIST OF LOAD MODULE PL1LOAD 


CSECT LOC 


00 
00 


00 
00 


IN CSECT 


A 
A 
SUNRESOLVED 
B 
Cc 
SUNRESOLVED 
S$ UNRESOLVED 
SUNRESOLVED 
SUNRESOLVED 
SUNRESOLVED 
S$ UNRESOLVED 
SUNRESOLVED 
SUNRESOLVED 
SUNRESOLVED 
IHESPRT 
IHESPRT 
IHESPRT 
IHES PRT 
THESPRT 
PL1TCO2 
PLITCO2 
PLITCO2 
PL1ITCO2 
PL1ITCO2 
PLITCO2 
PL1TCO2 
PL1TCO2 
PL1TCO2 
PLITC02 
PL1TCO2 
PLITCO2A 


MAP AND CROSS~REFERENCE LISTING 


IS REFERRED TO PY LMOD LOC CSECT LOC 


528 70 
600 148 
51¢ 64 

6C 


IN CSECT 


PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PL1TCO2A 
PLITCQ2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
IHENTRY 

PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLiTCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
PLITCO2A 
IHEMAIN 

PLITCO2 


PAGE 0003 


PAGE 0004 
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Sply 88S =ZL-g 


OBJECT MODULE LISTING 


ESD RECORD: 
ESDID TYPE 
0001  $SD(00) 
0002 ER(02) 
0003 ER(02) 

ESD RECORD: 
ESDID TYPE 
0004 ER(02) 
0005 ER(02) 
0006 ER(02) 

ESD RECORD: 
ESDID _— TYPE 
LD (01) 

TXT: 


ADDR=000000 ESDID= 


RLD RECORD: 


END RECORD: 


R PTR 


— re ee enn ee 


Figure 2-4. Sample LISTOBJ Output 


— 


NAME ADDR R/R/A ID/LTH 
RDONLYB1 0060000 03 00002C 
RDONLYB2 000000 40 404040 
RDONLYEL 000000 40 404040 

NAME ADDR R/R/A ID/LTH 
RDONLYE2 000000 40 404040 
RDWRTEO1 000000 40 404040 
RDWRTEO2 000000 40 404040 

NAME ADDR R/R/A ID/LTH 
LYB1 00000C 40 000001 

0001 TEXT: 

00000000 | 
P PTR FLAGS ADDR RETR 
0002 0001 1c 000018 0003 
0005 0001 zc 000024 0006 


15741SC103 020180171 


PAGE 0001 ~ 


00000001 


00000002 


00000002 


00000004 


90CED000 O5C098CE DOOOO7FE 9YOCED0O00 O5C098CE DOO007FE 00000000 00000000 00000000 00000000 


00000005 


00000006 


EL-Z LSM ‘Zsaideyo 


LISTIDR FOR LOAD MODULE SAMPLE PAGE 0001 


CSECT YR/DAY IMASPZAP DATA 
SAMP1 71/329 FIX12345 
SAMP 2 71/329 LEVEL003 
SAMP 4 71/329 PATCHOO1 
SAMP 4 71/329 PATCHO002 
SAMP 4 71/329 PATCH003 


= = om es Oe ee et em ee we oe ow Oe oe ce om oe te oe ee ae ee oe oe et om ey, oe ee ow ee ee ee ee wee cee we as ee oe we we we ee ee wee we we ee wee we we we we ee we ee we ee we we we ee we we ee we ee we ee we ee ee wee ewe ee ee we ee we ee we we we ee ee we wes we ow we we we we ww ew ww we we oe 


2 am eee aw om om ae am en a ee ow ae oe oe ee ee em oe oe oe om on ow Ge OD OD Om ee oe ee oo ow am on oe ee 0 ee ee we oe ee om ee oe oe oe oe oe oe om om om oe 0m me ee we em me ee ee we wre wee ee we wes we wee wee we ee we we es we es ee ee es es sw ee ws we we ww we ow ws im i ee Oe we we 


CSECT TRANSLATOR VR MD YR/DY 
SAMP1 360SAS037 21 00 71/329 
SAMP 2 360SAS037 21 00 71/329 
SAMP 3 360SAS037 21 00 71/329 
SAMP 4 360SAS037 21 00 71/329 
SAMP5 360SAS037 21 00 71/329 
CSECT YR/DAY USER DATA 

SAMP1 71/329 CHANGE LEVEL 01 

SAMP 2 71/329 VERSION 6 

SAMP 3 71/329 FIX LEVEL 2735 

SAMP 4 71/329 SORT SUBROUTINE 
SAMP5 71/329 CARD SCANNING SUBROUTINE 


Figure 2-5. Sample LISTIDR Output 


SPIV 8N1MES = pL 


NAME 
IGC00020 
IGCOOO06L 


MODIFIED 
NAME 

IGCO0OO5E 
IGCOO006L 


PAGEABLE 


AHLFSVC 
AHLPINT 
AHLSBCU1 
AHLSBUF 
AHLSETEV 
AHLSRB 
AHLSTAE 
AHLTACFV 
AHLTDIR 
AHLTEXT 
AHLTFOR 
AHLTLSR 
AHLTPID 
AHLTSRB 
AHLSTAE 
AHLTSYFL 
AHLTUSR 
AHLTXSYS 
AHLVCON 
AHLWTOMD 
AMDSYSO1 
AMDSYS03 
AMDSYS05 
AMDUSRFD 
AMDUSRFF 
AMDUSRF9 
CVAFGTF 
DCMBE1 
DCM181 
DCM183 
DCM271 


Figure 2-6. 


LOCATION 


LINK PACK 


LOCATION 


LINK PACK 


LOCATION 


01928000 


01956920 
01954570 


01971468 


0193A908 
019299C0 
01963850 
01989EE8 


01936000 
01939000 
01975178 
00F28000 


00B8E2 30 
00C4E730 


00CB8078 
00026318 


LENGTH 


AREA MAP - 


LENGTH 


AREA MAP - 


LENGTH 


00001998 


Q00006E0 
00000A90 


00000B98 


O00006F8 
00000640 
000007B0 
00000118 


00002AD8 
00001828 
99999358 
00001E60 


000003F8 
000008D0 


00000F88 
00000CE8 


Sample LISTLPA Output | 


EP ADDR 
00B42000 
00B419C0 


NUMERICALLY BY ENTRY POINT 
MAJOR LPDE NAME 


EP ADDR 
00B37FA0 
00B419C0 


ALPHABETICALLY BY NAME 
MAJOR LPDE NAME 


EP ADDR 
819B595E 
81963962 
8193A926 
8198F7EA 
8193A9D8 
8198F748 
81991F4A 
81991A90 
81928000 
819639EE 
8198F8C6 
819B596A 
81926A58 
81956920 
81954570 
819717D2 
81971468 
81971770 
819547B4 
8193A908 
819299C0 
81963850 
8198 9EE8 
81926E4C 
81936000 
91039000 
81975178 
00F28000 
00c4Cc000 
00B8E230 
00C4E730 
00C56328 
00CB8078 
00C26318 
00F24000 


MODIFIED LINK PACK AREA MAP - ALPHABETICALLY BY NAME 
MAJOR LPDE NAME 


AHLTVTAM 
AHLTXSYS 
AHLTSYFL 
AHLTSYSM 
AHLTSYFL 
AHLTSYSM 
AHLWSMOD 
AHLWSMOD 


AHLTXSYS 
AHLTSYSM 
AHLTVTAM 
AHLSETD 


AHLTPID 


AHLTPID 
AHLTFOR 


AHLSETD 


IMDUSRFF 
DCM3B3 


DCM270 


NAME 
IGCO005E 
IGGO19BN 


NAME 
IGGO019BN 
IGC00020 


NAME 
AHLDMPMD 
AHLEXT 
AHLFPI 
AHLFSSCH 
AHLMCER 
AHLREADR 
AHLSBLOK 
AHLSETD 
AHLSFEOB 
AHLSRM 
AHLSVC 
AHLTCCWG 
AHLTDSP 
AHLTFCG 
AHLTFRR 
AHLTPI 
AHLTSLIP 
AHLTSRM 
AHLTSVC 
AHLTSYSM 
AHLTVTAM 
AHLVCOFF 
AHLWSMOD 
AMDSYS00 
AMDSYS02 
AMDSYS04 
AMDSYS06 
AMDUSRFE 
AMDUSRF8 
CCKRIUWT 
DCMBEO 
DCM180 


DCM182 


DCM270 
DCM272 


LOCATION LENGTH 


N 00.12SEC VIRT 


LOCATION LENGTH 


N 00.12SEC VIRT 


LOCATION LENGTH 


01977C08 


01926000 


0192A000 


0192D000 


0192F000 


01931000 
0198F508 
019B5940 
O19B6F40 
019916B0 
01934000 
019BB648 
0193B000 
01961C08 


OOBF1008 


00F26000 
00054020 
00F24000 
00E1LE830 


000003F8 


00001708 


00002378 


000016D0. 


00001C50 


00002768 
OOOOOAFS8 
600006C0 
000000C0 
00000950 
00001208 
00000548 
00002038 
000003F8 
000006C8 


00001360 
O0000FEO 
000014E0 
000007D0 


EP ADDR 
00B37FA0 
00B414D8 
200K SYS 


EP ADDR 
00B414D8 
00B42000 
200K SYS 


EP ADDR 
81926EBE 
8198F660 
8193A9FC 
8193A946 
81926450 
81977C08 
819916B0 
81926000 
819917EE 
81963A62 
8198F61A 
8191A000 
81971658 
8192D000 
81954694 
8197147E 
8192F000 
8195458C 
819316000 
8198F508 
819B5940 
819BOF40 
819916B0 
81934000 
819BB648 
8193B000 
81961C08 
OOBF1008 
00008590 
00C48000 
00056328 
00F260090 
00054020 
0OF24000 
O0OE1LE830 


MAJOR LPDE NAME 


276K 


MAJOR LPDE NAME 


276K 


MAJOR LPDE NAME 


AHLSETD 
AHLTSYSM 
AHLTSYFL 
AHLTSYFL 
AHLSETD 


AHLWSMOD 
AHLWSMOD 
AHLTXSYS 
AHLTSYSM 
AHLTPID 


AHLTFOR 
AHLTPID 


AHLTFOR 


IMDUSRF8 
ISTAICIR 
DCM3B3 


Examples 


The following examples show sample uses of LIST. 


Example 1: Listing Several Object Modules 


In this example, LIST is used to list all object modules contained in the data set 
named OBJMOD, and three specific object modules from another data set called 


OBJMODS. 
//OBJLIST JOB  MSGLEVEL=(1,1) 
//LISTSTEP EXEC  PGM=AMBLIST,REGION=64K 
//SYSPRINT DD ——«-SYSOUT=A 
//OBJLIB DD  _ DSN=OBJMODS ,DISP=SHR 
//OBJSDS DD DSN=OBJMOD,DISP=SHR 
//SYSIN DO * 
LISTOBJ DDN=OBUSDS, 
TITLE=(‘OBJECT MODULE LISTING OF OBJSDS' ,20) 
LISTOBJ DDN=OBJLIB,MEMBER=(0BJ1,0BJ2,0BU3) , 


TITLE=('OBJECT MODULE LISTING OF OBJ1 OBJ2 0BJ3',20) 
/* 


OBJLIB and OBJSDS DD Statements 
define input data sets that contain object modules. 


SYSIN DD Statement | 
defines the data set in the input stream containing LIST control statements. 


LISTOBJ Control Statement #1 
instructs LIST to format the data set defined by the OBJSDS DD statement, 
treating them as a single member. It also specifies a title for each page of 
output, to be indented 20 characters from the left margin. 


LISTOBJ Control Statement #2 
instructs LIST to format three members of the partitioned data set (PDS or 
PDSE) defined by the OBJLIB DD statement. It also specifies a title for each 
page of output, to be indented 20 characters from the left margin. 


Chapter 2. LIST 2-15 


Example 2: Listing Several Load Modules 
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In this example, LIST is used to produce formatted listings of several load modules. 


//LOADLIST JOB MSGLEVEL=(1,1) 
//LISTSTEP EXEC PGM=AMBLIST , REGION=64K 
//SYSPRINT DD SYSOUT=A 
//SYSLIB DD DSNAME=SYS1.LINKLIB,DISP=SHR 
//LOADLIB DD DSNAME=LOADMOD ,DISP=SHR 
//SYSIN DD * 
LISTLOAD OUTPUT=MODLIST ,DDN=LOADLIB, 
MEMBER=TESTMOD, 
TITLE=("LOAD MODULE LISTING OF TESTMOD' ,20) 
LISTLOAD OUTPUT=XREF ,DDN=LOADLIB, 
MEMBER=(MOD1,MOD2,MOD3) , 
TITLE=('XREF LISTINGS OF MOD1 MOD2 AND MOD3',20) 
LISTLOAD TITLE=('XREF&LD MOD LSTNG-ALL MOD IN LINKLIB',20) 


ye 


SYSLIB DD Statement 
defines an input data set, SYS1.LINKLIB, that contains load modules to be 
formatted. 


LOADLIB DD Statement 
defines a second input data set. 


SYSIN DD Statement 
defines the data set (in the input stream) containing the LIST control statements. 


LISTLOAD Control Statement #1 
instructs LIST to format the control and text records including the external 
symbol dictionary and relocation dictionary records of the load module 
TESTMOD in the data set defined by the LOADLIB DD statement. It also 
- specifies a title for each page of output, to be indented 20 characters from the 
left margin. 


LISTLOAD Control Statement #2 | 
instructs LIST to produce a module map and cross-reference listing of the load 
modules MOD1, MOD2, and MODS in the data set defined by the LOADLIB DD 
statement. It also specifies a title for each page of output, to be indented 20 
characters from the left margin. 


LISTLOAD Control Statement #3 


instructs LIST to produce a formatted listing of the load module and its map and 
cross-reference listing. Because no DDN= parameter is included, the input 
data set is assumed to be the one defined by the SYSLIB DD statement. 
Because no MEMBER= parameter is specified, all load modules in the data set 
will be processed. This control statement also specifies a title for each page of 
output, to be indented 20 characters from the left margin. 


Example 3: Listing IDR Information for Several Load Modules 


In this example, LIST is used to list the CSECT identification records in several load 
modules. 


//IDRLIST JOB MSGLEVEL=(1,1) 
//LISTSTEP EXEC PGM=AMBLIST ,REGION=64K 


//SYSPRINT — DD SYSOUT=A 

//SYSLIB DD DSN=SYS1. LINKLIB,DISP=SHR 
//LOADLIB DD DSN=LOADMODS ,DISP=SHR 
//SYSIN DD 


LISTIDR TITLE=('IDR LISTINGS OF ALL MODS IN LINKLIB',20) 
LISTIDR OQUTPUT=IDENT,DDN=LOADLIB,MEMBER=TESTMOD 
TITLE=('LISTING OF MODIFICATIONS TO TESTMOD' ,20) 
LISTIDR OUTPUT=ALL,DDN=LOADLIB,MEMBER=(MOD1,MOD2,MOD3) , 
TITLE=('IDR LISTINGS OF MOD1 MOD2 MOD3' ,20) 
LISTIDR DDN=LOADLIB,MODLIB 


Vig 


SYSLIB DD Statement 
defines the input data set SYS1.LINKLIB, which contains load modules to be 
processed. 


LOADLIB DD Statement 
defines a second input data set. 


SYSIN DD Statement 
defines the data set (in the input stream) containing the LIST control statements. 


LISTIDR Control Statement #1 
instructs LIST to list all CSECT identification records for all modules in 
SYS1.LINKLIB (this is the default data set since no DDN= parameter was 
included). It also specifies a title for each page of output, to be indented 20 
characters from the left margin. 


LISTIDR Control Statement #2 
instructs LIST to list CSECT identification records that contain SPZAP or 
user-supplied data for load module TESTMOD. TESTMOD is a member of the 
data set defined by the LOADLIB DD statement. This control statement also 
specifies a title for each page of output, to be indented 20 characters from the 
left margin. | 


LISTIDR Control Statement #3 
instructs LIST to list all CSECT identification records for load modules MOD1, 
MOD2, and MOD3. These are members in the data set defined by the LOADLIB 
DD statement. This control statement also specifies a title for each page of 
output, to be indented 20 characters from the left margin. 


LISTIDR Control Statement #4 
instructs LIST to list CSECT identification records that contain SPZAP or 
user-supplied data for the LOADLIB data set. The module summary print out its 
suppressed. 
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Example 4: Verifying an Object Deck 


In this example, LIST is used to format and list an object module included in the 
input stream. 


//LSTOBJDK JOB MSGLEVEL=(1,1) 
// EXEC PGM=AMBLIST,REGION=64K . 
//SYSPRINT DD SYSOUT=A 
/ /OBJDECK DD * 
object deck 
Vhs 
| //SYSIN DD * 
LISTOBJ DDN=OBJDECK, 
TITLE=('OBJECT DECK LISTING FOR MYJOB' ,25) 
/* 
OBJDECK DD Statement 


defines the input data set, which follows immediately. In this case, the input 
data set is an object deck. 


SYSIN DD Statement 
defines the data set containing LIST control statements, which follows 
immediately. 


LISTOBJ Control Statement 
instructs LIST to format the data set defined by the OBJDECK DD statement. It 
also specifies a title for each page of output, to be indented 20 characters from 
the left margin. 
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Example 5: Verifying Several Load Modules 


This example shows how to use LIST to verify all three modules. Assume that an 
unsuccessful attempt has been made to link edit an object module with two load 
modules to produce one large load module. 7 


//LSTLDOBU JOB  MSGLEVEL=(1,1) 
// EXEC  PGM=AMBLIST,REGION=64K 
//SYSPRINT DD SYSOUT=A 
//OBJMOD DD DSN=MYMOD ,DISP=SHR 
//LOADMOD1 DD DSN=YOURMOD , DISP=SHR 
//LOADMOD2 DD DSN=HISMOD ,DISP=SHR 
//SYSIN DD * 
LISTOBJ DDN=OBJMOD, 
TITLE=(‘OBJECT LISTING FOR MYMOD' ,20) 
LISTLOAD DDN=LOADMOD1 , OUTPUT=BOTH, 
TITLE=('LISTING FOR YOURMOD' ,25) 
LISTIDR DDN=LOADMOD1, OUTPUT=ALL, 
TITLE=('IDRS FOR YOURMOD' ,25) 
LISTLOAD DDN=LOADMOD2 , OUTPUT=BOTH, 
TITLE=(‘LISTING FOR HSMOD' ,25) 
LISTIDR DDN=LOADMOD2, OUTPUT=ALL, 


TITLE=('IDRS FOR HISMOD' ,25) 
/* 


OBJMOD DD Statement 
defines an input load module data set. 


LOADMOD1 and LOADMOD2 DD Statements 
define input load module data sets. 


SYSIN DD Statement 
defines the data set containing LIST control statements, which follows 
immediately. 


LISTOBJ Control Statement 
instructs LIST to format the data set defined by the OBJMOD DD statement. It 
also specifies a title for each page of output, to be indented 20 characters from 
the left margin. | 


LISTLOAD Control Statement #1 
instructs LIST to format all records associated with the data set defined by the 
LOADMOD1 DD statement. It also specifies a title for each page of output, to be 
indented 25 characters from the left margin. 


LISTIDR Control Statement #1 
instructs LIST to list all CSECT identification records associated with the data 
set defined by the LOADMOD1 DD statement. It also specifies a title for each 
page of output, to be indented 25 characters from the left margin. . 


LISTLOAD Control Statement #2 
instructs LIST to format all records associated with the data set defined by the 
LOADMOD2 DD statement. It also specifies a title for each page of output, to be 
indented 25 characters from the left margin. 
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LISTIDR Control Statement #2 
instructs LIST to list all CSECT identification records associated with the data 
set defined by the LOADMOD2 DD statement. It also specifies a title for each 
page of output to be indented 25 characters from the left margin. 


Example 6: — a System Nucleus and Mapping the Link Pack Area 


2-20 Service Aids 


This example shows how to use the LISTLOAD and LISTLPA control statements to 
list a system nucleus and map the fixed link pack area, the modified link pack area, 
and the pageable link pack area. Note that in this example the data set containing 
the nucleus is named SYS1.NUCLEUS, and the nucleus occupies the member named 
IEANUCO1. The map no longer represents the IPL version of the nucleus and 
message AMB129i will be issued. Use IPCS to format the NUCMAP. For 
information on using IPCS see the IPCS User’s Guide. 


//LISTNUC JOB MSGLEVEL=(1,1) 
//STEP EXEC PGM=AMBLIST , REGION=100K 
//SYSPRINT DD SYSOUT=A 
//SYSLIB DD DSN=SYS1.NUCLEUS , DISP=SHR, UNIT=3330, 
//  VOL=SER=nnnnn 
//SYSIN DD - 
LISTLOAD DDN=SYSLIB,MEMBER=IEANUCO1, 
TITLE=('LISTING FOR NUCLEUS IEANUCO1' 25) 
| LISTLPA 
/* 


SYSLIB DD Statement 
defines the input data set, which in this case contains the nucleus. 


SYSIN DD Statement 
defines the data set containing LIST control statements, which follows 
immediately. 


LISTLOAD Control Statement 
instructs LIST to format the control and text records including the external 
symbol dictionary and relocation dictionary records of the load module 
IEANUCO01 in the data set defined by the SYSLIB DD statement. It also specifies 
a title for each page of output, to be indented 25 characters from the left margin. 


LISTLPA Control Statement 
instructs LIST to map the fixed link pack area, the modified link pack area, and 
the pageable link pack area. 
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Introduction — 


AMDSADMP (SADMP) is a stand-alone program designed to dump storage froma 
system that has failed. It is available to help you diagnose the failed system. 


SADMP produces an unformatted dump of central (also called real) storage and 
parts of paged-out virtual storage, on a tape. This is also called a ‘high-speed’ 
stand-alone dump. The interactive problem control system (IPCS) can be used to 
format the dump and view it on the console or print it on a printer. For information 
on using IPCS, see the /PCS User’s Guide. 


SADMP can also produce a formatted dump of portions of central storage, on a tape 
or printer. This is called a ‘low-speed’ stand-alone dump. 


You can use the IEBPTPCH utility program to print the formatted dump tape. 


You can generate different versions of SADMP by coding several AMDSADMP 
macros and varying the values of keywords on the macros. AMDSADMP is supplied 
in the system library SYS1.MACLIB. The SADMP program is generated under the 
operating system, but its execution is a stand-alone operation. 


Notes: 


1. Stand-alone dump uses only on-line devices. When you dump to or from 
devices that have both real and virtual addresses, specify only the real 
addresses to SADMP. SADMP must reside on an on-line storage device. 


2. You cannot direct SADMP output to its residence volume. | 


3. The SADMP residence volume, output device, and console do not have to be 
attached to the same processor. 


4. To ensure that SADMP is available and successfully processes, the 
SYS1.PAGEDUMP data set should not be deleted or moved to another volume or 
pack. 


The rest of this chapter describes the SADMP program and SADMP output, and 
shows how to generate and execute SADMP. 
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SADMP Program 


There are two types of SADMP programs: 
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1. 


Unformatted (high-speed dump) 


e data set resides on a direct access device with output directed to a tape 
~ volume 


e data set resides on a tape device, with output directed to a tape volume 


2. Formatted (low-speed dump) 


e data set resides on a direct access device with output directed to a tape 
volume 


e data set resides on a direct access device with output directed to a printer 


SADMP unformatted output is intended for processing by IPCS. 


The unformatted high-speed version of SADMP dumps all central storage and some 
areas of virtual storage not backed by central storage. The output includes: 


The prefixed save areas (PSAs) 

The nucleus and extended nucleus 

The system queue area (SQA) and the extended SQA 
The common service area (CSA) and the extended CSA 


Subpools 203-205, 213-215, 229, 230, 236, 237, 247, and 248 for the eligible 
address spaces based on the MINASID option specified 


The local system queue area (LSQA) and the extended LSQA for eligible 
address spaces based on the MINASID option specified 


A dump title 
The processor STORE STATUS information for each processor 


Main storage from address 0 to the top of main storage in absolute address. 
sequence (some blocks may be missing because of off-line storage elements) 


Instruction trace data created by the instruction address trace 
Vector data for each processor that has a Vector Facility installed. 


Virtual storage areas selected by the DUMP= keyword, or selected by the 
operator at execution time. 


A message log, normally consisting of all console messages issued by the 
virtual dump program (whether or not messages were suppressed). 


Eligible address spaces that are physically swapped-in or all address spaces as 
specified by the MINASID keyword or by the operator at execution. 


lf SADMP detects an internal error, the output may also include one or more SADMP 
self-dumps. 


To format and print the SADMP message log, invoke the SADMPMSG VERBEXIT 
under IPCS. | 


SADMP dumps the instruction trace data (created by the instruction address trace) 
only if SADMP loads the virtual storage dump program, AMDSAPGE. SADMP loads 
AMDSAPGE only when the central (also called real) storage dump program 


AMDSARDM does not detect any unexpected program errors and when SADMP 
determines that the virtual environment is valid. SADMP does not dump the 
instruction trace data (created by instruction address trace) when any of the 
following conditions exist: 


e The prefix register is invalid. 


e Any of the following control blocks fail the SADMP validity check: the CVT, the 
RSM control blocks, or the SADMP RLT. 


e The LPA has not been initialized. 
¢ SADMP cannot read AMDSAPGE into storage due to an 1/O error. 


You can request that SADMP dump additional storage by specifying dump tailoring 
options. See “Dumping Additional Storage” on page 3-19. 


The formatted low-speed version of SADMP produces a dump title specified at dump 
execution time, followed by processor related data for each available processor, 
followed by a dump of user selected areas of central storage. 


lf your program contains Vector Facility data and you are unable to dump that data, 
one of the following conditions exist: 
1. The Vector Facility was not on-line at the time the dump was requested. 


2. A machine check occurred on the processor on which your program was 
running while SADMP was issuing vector instructions. 


3. While dumping vector data, an error occurred in SADMP. Some data might be 
missing on the SADMP output tape. 


SADMP does not issue a message if it cannot dump data. 
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Creating the SADMP Program 


Before you can run SADMP, you must create a SADMP program in ready-to-load 
form on an appropriate device. The pace for creating a ready-to-load SADMP 
program is as follows: 


1. Device selection - Select a tape or direct access device as the SADMP IPL 
volume (“residence volume”). If the residence volume is a direct access 
device, make sure that it does not already contain a SYS1.PAGEDUMP dataset; 
otherwise, SADMP initialization will fail. The SADMP volume mount attribute 
must be PRIVATE. | 


2. Dump specification - Specify the type of SADMP program that you want by 
coding the AMDSADMP macro. 


3. Residence volume initialization - Put the SADMP program onto the residence 
volume in ready-to-load form, using either a two-stage generation or a one-step 
generation. In two-stage generation, first assemble the AMDSADMP macro. 
This will produce the input required to run the second stage of the JCL. Then 
run stage two to initialize the SADMP residence volume. In one-step 
generation, execute the AMDSAOSG program as a single job step, using the 
AMDSADMP macro as input data (SYSIN control statement). 


With both two-stage or one-step generation, SADMP residence volume initialization 
consists of three phases: | 


e Phase One 


— The AMDSADM2 macro is assembled to produce the SADMP central storage 
dump program AMDSARDM, which dumps central storage, and the SADMP. 
common communication table AMDSACCT, an internal control block. 


e Phase Two 


— The SADMP build module AMDSABLD puts the output from phase one onto 
the residence volume in ready-to-load form. AMDSABLD locates the 
SADMP IPL program AMDSAIPL and the SADMP virtual storage dump 
program AMDSAPGE, and puts them onto the residence volume. 


e Phase Three 


— Ifthe residence volume is a direct access device, the device utility ICKDSF 
is invoked to put SADMP’s IPL text onto the device’s IPL track (cylinder 0, 
track 0). 
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Considerations in Creating Stand-Alone Dumps 


The JCL for the AMDSADM2 assembly in stage two of the two-stage generation must 
provide a SYSLIB DDNAME that refers to a macro library containing the system 
macros BLSRDRPX, BLSRDATS, IEZBITS, IHAIRB, IHAMSF, IHAORB, IHAPSA, 
IHASCCB, and IHASCHIB. The same is true of any SYSLIB DDNAME in the JCL for 
the one-step generation program AMDSAOSG. 


If you are using MVS/SP 3.1.3, some of these system macros are in SYS1.MODGEN, 
so make sure that the SYSLIB DDNAME concatenates SYS1.MODGEN to 
SYS1.MACLIB. Your installation should catalog the SYS1.MODGEN data set before 
creating the SADMP program; otherwise, the JCL that AMDSADMP produces will 
fail to build the stand-alone dump program. 


You should consider some form of password or other security protection for 
SYS1.PAGEDUMP; this data set contains copies of several pages of central storage 
whose contents are unpredictable. You should also consider protecting the SADMP 
macros and modules from unauthorized modification. 


To ensure that SADMP is available and successfully processes, the 
SYS1.PAGEDUMP data set should not be deleted or moved to another volume or 
pack. 


You should consider which MINASID keyword option default is appropriate for your 
installation: 


¢ MINASID(PHYSIN) will reduce the overall execution time of SADMP. 

¢ MINASID(ALL) will cause SADMP output to contain a more complete image of 
your system at the time the dump is taken but will also increase the time 
required for execution. 


Note: ALL address spaces are likely to be needed for hangs, enabled waits, and 
performance problems. PHYSIN should suffice for coded waits, loops, and spin 
loops. 
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Dump Specification: Coding the AMDSADMP Macro 


This section describes the syntax of the AMDSADMP macro instruction used to 
produce both high-speed and low-speed versions of the dump program. For 
examples using the AMDSADMP macro, see the “SADMP Examples” on page 3-35. 
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Syntax of the AMDSADMP Macro for an Unformatted Dump Program 
Figure 3-1 shows the AMDSADMP macro parameters. 


[symbol] AMDSADMP [TYPE={HI|UNFORMATTED}] 
[, IPL={Tunit|Dunit |DSYSDA} | 


[, VOLSER={volser | SADUMP}] [ ,ULABEL={PURGE | NOPURGE} ] 


[ CONSOLE=({cnum| (cnum, ctype) [,(cnum,ctype)]...|O1F,3278}) | 
r.sysUT={unit|SYSDA}] [,OUTPUT={Tunit|T282}] 
[,DUMP='dto'][,PROMPT] [, LOADPT={1oadpt|X'1000' }] 
[ ,MSG={ACTION|ALL}] [,MINASID={ALL | PHYSIN}] 


Figure 3-1. Format of AMDSADMP Macro Instruction Used to Generate a High-Speed 
Dump Program 


symbol 
an arbitrary name you can assign to the AMDSADMP macro instruction. © 
SADMP uses this symbol to create a job name for use in the initialization step. 


AMDSADMP 
the name of the macro instruction. 


TYPE = {HIJUNFORMATTED} 
indicates the high-speed version of the dump program. When you omit this 
parameter, SADMP assumes TYPE =HI as the default. TYPE =HI and 
TYPE =UNFORMATTED have the same meaning. 


IPL = {Tunit|Dunit|DSYSDA} 
indicates the unit address or the device type of the SADMP residence volume. 

_ The first character indicates the volume type; T for tape, D for DASD. SADMP 
uses the unit character string as the UNIT = value to allocate the residence 
volume for initialization. IPL=DSYSDA is the default. When you specify IPL=T, 
SADMP assumes T3400. When you specify IPL=D, SADMP assumes DSYSDA. 


VOLSER = {volser|SADUMP} 
indicates the VOL=SER= value to allocate the residence volume for 
initialization. When you specify a tape volume, it must be NL (no labels). 
VOLSER = SADUMP is the default. 


ULABEL = {PURGE|NOPURGE} 
indicates whether SADMP deletes (PURGE) or r retains (NOPURGE) existing user 
labels on a DASD residence volume. When you specify NOPURGE, the SADMP 
program is written on cylinder 0 track 0 of the residence volume, immediately 
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following all user labels. If the user labels occupy so much space that the 
SADMP program does not fit on track 0, the initialization program issues an 
error message and terminates. 


ULABEL = NOPURGE is the default. 


CONSOLE = ({cnum|(cnum,ctype)[,(cnum,ctype) |.../01F,3278}) 
indicates the device numbers and device types of the system consoles that 
SADMP is to use while taking the dump. When you specify CONSOLE = cnum, 
SADMP assumes (cnum,3278). You can specify from 2 to 21 consoles by coding: 


CONSOLE=((cnum, ctype) , (cnum,ctype) ,[, (cnum,ctype) ]...) 
The 3277, 3278, 3279, and 3290 device types are valid, and are interchangeable. 
CONSOLE = (01F,3278) is the default. 


SYSUT = {unit|SYSDA} 
specifies the UNIT = value of the device that SADMP uses for work files during 
the initialization stage. You may specify the device as a group name (for 
example, SYSDA), a device type (for example, 3330), or a unit address (for 
example, 131). SYSUT=SYSDA is the default. 


OUTPUT = {Tunit|T282} 
specifies the unit address of the output device that SADMP uses as a default 
value if you use the EXTERNAL INTERRUPT key to bypass console 
communication, or if you give a null response to message AMDOO1A during 
SADMP IPL. You must always direct high-speed dump output to a tape device. 
This parameter does not allow the same flexibility that the IPL parameter allows 
(for example, T3400 is not a valid OUTPUT parameter). With a response to 
message AMDO01A, you can override the address specified on OUTPUT= at 
execution time. OUTPUT = T282 is the default. 


DUMP = 'dto' 
indicates additional virtual storage that you want dumped. This storage is 
described as address ranges and subpools in address spaces. See the topic 
“Dumping Additional Storage” on page 3-19. When you do not specify DUMP, 
SADMP does not dump any additional storage unless you specify PROMPT. 


PROMPT 
causes SADMP, at execution time, to prompt you for additional virtual storage 
that you want dumped. You may respond with the same information that can be 
specified for the DUMP keyword. See the topic “Dumping Additional Storage” 
on page 3-19. When you do not specify PROMPT, SADMP does not prompt you 
to specify additional storage that you want dumped. 


LOADPT = {loadpt|X'1000'} 
indicates the real address where SADMP will load the high-speed version of the 
dump program. The load point address must be a hexadecimal number larger 
than X'FFF' and smaller, by at least X'15000', than the highest real address in 
the configuration. The load point is rounded down to a page boundary. The 
SADMP central storage dump program requires four page frames of contiguous 
central storage. With the default LOADPT of X'1000', the dump program will 
use X'1000' - X'4FFF'. 


An alternate SADMP version can be created so that the dump program can be 
|PLed even if there is bad or offline storage at locations X'1000' - X'15000'. 
The LOADPT can be set equal to one megabyte (X'100000') less than the 
address at the top of on-line central storage. 
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MSG = {ACTION|ALL} | 
indicates the type of SADMP messages that are to appear on the console. When 
you specify ACTION, SADMP writes only messages that require operator action. 
When you specify ALL, SADMP suppresses no messages. ALL is the default. 


This keyword has no effect on the SADMP message log; even if you specify 
MSG=ACTION, the SADMP virtual dump program writes messages to the 
message log on the output tape. | 


MINASID = {ALL|PHYSIN} 
indicates the status of the address spaces that are to be included in the minimal 
dump. Specify PHYSIN to dump the minimum virtual storage (LSQA and 
selected system subpools) for the physically swapped-in address spaces only. 
Specify ALL to dump the minimum virtual storage (LSQA and selected system 
subpools) for all of the address spaces. ALL is the default. © 


At execution, if PHYSIN was specified, SADMP writes message AMD082I to the 
operator’s console to warn the operator that some virtual storage may be 
excluded from the dump. : 


Syntax of the AMDSADMP Macro for a Formatted Dump Program | 
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Figure 3-2 shows the syntax of the AMDSADMP macro instruction for producing a 
low-speed dump program. 


[symbol] AMDSADMP TYPE={LO|FORMATTED}}[, IPL={Dunit|DSYSDA}] 


[, VOLSER={volser|SADUMP}] [,ULABEL={PURGE | NOPURGE} | 


[,CONSOLE=({cnum|(cnum,ct) [,(cnum,ct)] ...|@1F.3278}) — 
[,SYSUT={unit | SYSDA} ] [,OUTPUT={Tunit | Punit | POGE} | 


[,ADDR={VI RTUAL | REAL}] [, LOADPT={1oadpt| '1000'}] 


[,MSG={ACTION| ALL} ] 


Figure 93-2. Format of AMDSADMP Macro Instruction Used to Generate a Low-Speed 
Dump Program 


symbol 
an arbitrary name you can assign to the AMDSADMP macro instruction. 
SADMP uses this symbol to create a job name for use in the initialization step. 


AMDSADMP 
the name of the macro instruction. 


TYPE = {LO|FORMATTED} 
specifies the low-speed version of the dump program. When you do not specify 
TYPE=, SADMP uses a high-speed dump as the default. LO and FORMATTED | 
have the same meaning. 


IPL = {Dunit|DSYSDA} 
specifies the unit address or the device type of the SADMP residence volume. 
The first character must be D (for DASD). SADMP uses the unit character string 
as the UNIT = value to allocate the residence volume for initialization. 
IPL=DSYSDA is the default. 


OUTPUT = {Tunit|Punit|POOE} 
specifies the device to which SADMP writes output. The first character specifies 
the output device type: P for printer, T for tape. The unit character string 
specifies the unit address that SADMP uses if you use the EXTERNAL 
INTERRUPT key to bypass console communication during SADMP IPL. This 
parameter does not allow the same flexibility that the IPL parameter allows (for 
example, T3400 is not a valid OUTPUT parameter). At execution time, you can 
override the address that you specified on OUTPUT = with a response to 
message AMDOO1A. Note that a null response causes SADMP to use the 
OUTPUT = value. OUTPUT =POOE (that is, a printer) is the default. 


VOLSER = {volser|SADUMP} 
specifies the VOL=SER= value to allocate the residence volume for 
initialization. VOLSER=SADUMP is the default. 


CONSOLE = ({cnum|(cnum,ctype)|[ ,(cnum,ctype) |...|01F,3278}) 
indicates the device numbers and device types of the system consoles that 
SADMP is to use while taking the dump. When you specify CONSOLE =cnum, 
SADMP assumes (cnum,3278). You can specify from 2 to 21 consoles by coding: 


CONSOLE=((cnum, ctype) , (cnum,ctype) ,[, (cnum, ctype) ]...) 
The 3277, 3278, 3279, and 3290 device types are valid, and are interchangeable. 
CONSOLE = (01F,3278) is the default. 


SYSUT = {unit|SYSDA} 
specifies the UNIT = value of the device that SADMP uses for work files during 
the initialization stage. You may specify the device as a group name (for 
example, SYSDA), a device type (for example, 3330), or a unit address (for 
example, 131). SYSUT=SYSDA is the default. 


ULABEL = {PURGE|NOPURGE} 
specifies whether SADMP deletes (PURGE) or retains (NOPURGE) existing user 
labels on a DASD residence volume. When you specify NOPURGE, the SADMP 
program is written on cylinder 0 track 0 of the residence volume, immediately 
following all user labels. If the user labels occupy so much space that the 
SADMP program does not fit on track 0, the initialization program issues an 
error message and terminates. ULABEL=NOPURGE is the default. 


ADDR = {REAL|VIRTUAL} 
specifies the default action that SADMP takes if the console is unavailable or if 
you specify end of block to a prompting message for the type of dump desired. 
REAL specifies that central storage (from 0 to 2048 megabytes) is dumped in 
ascending order by real addresses. VIRTUAL specifies that central storage 
(from 0 to 2048 megabytes) is dumped in ascending order by virtual addresses 
using the segment table of the address space in control when the IPLed 
processor was stopped or if no STORE STATUS was done, the master address 
space. The default is REAL. 


Note that the ADDR keyword is valid for low-speed SADMP only. 
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LOADPT = {loadpt|X'1000'} | 
specifies the real address where SADMP loads the low- -speed version of the 
dump program. The address 'loadpt' must be a hexadecimal number larger 
than X'FFF' and smaller, by at least X'4000', than the highest real address in 
the configuration. The load point is rounded down to a page boundary. The 
SADMP central storage dump program requires four page frames of contiguous 
central storage. With the default LOADPT of X'1000', the dump program will 
use X'1000' - X'4FFF'. 


An alternate SADMP version can be created so that the dump program can be 
IPLed even if there is bad or offline storage at locations X'1000' - X'4FFF’. The 
LOADPT can be set equal to one megabyte (X'100000') less than the address at 
the top of on-line central storage. 


MSG = {ACTION|ALL} 
specifies the type of SADMP messages that appear on the console. When you 
specify ACTION, SADMP writes only messages that require operator action. 
When you specify ALL, SADMP writes all messages. ALL is the default. 


[| send of GENERAL-USE PROGRAMMING INTERFACE —SCd 


Two-Stage Generation: 


Assembling the Macro Instruction 
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Figure 3-3 and Figure 3-4 are examples of the JCL statements needed to assemble 
the AMDSADMP macro. Figure 3-3 is a sample for installations using a release 
prior to MVS/SP 3.1.3; Figure 3-4 on page 3-11 is for installations using MVS/SP 
3.1.3. In both examples, the stage two JCL is placed in the SYSPUNCH data set. 


//ASSEMSAD —-JOB MSGLEVEL=(1,1) 
//ASM EXEC PGM=IEV90, PARM='DECK' 
//SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR 
//SYSUT1 DD UNIT=SYSDA, SPACE=(1700, (400,50) ) 
//SYSPRINT DD SYSOUT=A 
//SYSPUNCH DD SYSOUT=B 
//SYSIN DD * 
AMDSADMP —-TYPE=HI 
END 
ie 


Figure 3-3. Sample JCL to Assemble AMDSADMP Macro (For releases of MVS/SP Version 
3 prior to MVS/SP 3.1.3) 


/ /ASSEMSAD JOB MSGLEVEL=(1,1) 


//ASM EXEC PGM=IEV90, PARM='DECK' 
//SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR 
DD DSN=SYS1.MODGEN ,DISP=SHR 
//SYSUT1 DD UNIT=SYSDA, SPACE=(1700, (400,50) ) 
//SYSPRINT DD SYSOUT=A 
//SYSPUNCH DD SYSOUT=B 
//SYSIN DD * 
AMDSADMP —- TYPE=HI 
END 
i 


Figure 3-4. Sample JCL to Assemble AMDSADMP Macro (MVS/SP 3.1.3) 
The SYSLIB data set must contain the AMDSADMP macro. 


To direct the punched output to tape, use the following SYSPUNCH DD statement: 


//SYSPUNCH DD UNIT=tape, LABEL=(,NL) ,DISP=(NEW,KEEP) , 
// VOL=SER=SCRTCH 


To direct the punched output to a new direct access data set, use the following 
SYSPUNCH DD statement: 


//SYSPUNCH DD UNIT=dasd, SPACE=(80, (30,10) ) ,DSN=dsname, 
// DISP=(NEW,KEEP) , VOL=SER=volser 
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Assembling Multiple Versions of AMDSADMP | 
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You can assemble multiple versions of AMDSADMP at the same time, eauided that 


_each version specifies a different residence volume. Differentiate between versions 


by coding a unique symbol at the beginning of each macro instruction. AMDSADMP 
uses the symbol you indicate to create unique stage-two job names. The output 
from a multiple assembly is a single listing and a single object deck, which may be 
broken into separate jobs if desired.Figure 3-5 and Figure 3-6 show sample JCL for 
coding multiple versions of AMDSADMP. Figure 3-5 is a sample for installations 
using releases prior to MVS/SP 3.1.3; Figure 3-6 is for installations using MVS/SP 
3.123; 


//MULTISAD JOB MSGLEVEL=(1,1) 

//ASM EXEC PGM=IEV90,PARM=' DECK’ 

//SYSLIB DD  DSN=SYS1.MACLIB,DISP=SHR 
//SYSUT1 DD UNIT=SYSDA,SPACE=(1700, (400,50) ) 
//SYSPRINT DD SYSOUT=A 

//SYSPUNCH DD SYSOUT=B 

//SYSIN. DD * 


| HITAPE AMDSADMP IPL=1T3400, VOLSER=SADMP1 | 
HIDASD1 AMDSADMP VOLSER=SADMP2 ,MINASID=PHYSIN 
HIDASD2 AMDSADMP VOLSER=SADMP3 , LOADPT=X' 10000000 ' 
LOTAPE AMDSADMP TYPE=LO,OUTPUT=T282 , VOLSER=SADMP4 
LOPRINTER AMDSADMP TYPE=LO,VOLSER=SADMP5 
END 
/* 


Figure 3-5. Sample JCL for Assembling Multiple Versions of AMDSADMP Macro (For 
releases of MVS/SP Version 3 prior to MVS/SP 3.1.3) 


//MULTISAD JOB MSGLEVEL=(1,1) 

//ASM EXEC PGM=IEV90,PARM='DECK' 

//SYSLIB ODD DSN=SYS1.MACLIB,DISP=SHR 

Ji DD  DSN=SYS1.MODGEN,DISP=SHR 
//SYSUT1 DD UNIT=SYSDA,SPACE=(1700, (400,50) ) 
//SYSPRINT DD SYSOUT=A 

//SYSPUNCH DD SYSOUT=B 

//SYSIN. DD * 


HITAPE AMDSADMP IPL=T3400, VOLSER=SADMP1 
HIDASD1 AMDSADMP VOLSER=SADMP2 ,MINASID=PHYSIN 

| HIDASD2 AMDSADMP VOLSER=SADMP3 , LOADPT=X‘ 10000000 ' 
LOTAPE AMDSADMP TYPE=LO,OUTPUT=T282 , VOLSER=SADMP4 
LOPRINTER AMDSADMP TYPE=LO,VOLSER=SADMP5 


END 
/* 
Figure 3-6. Sample JCL for Assembling Multiple Versions of AMDSADMP Macro (MVS/SP 
3.7.3) 


Message Output from AMDSADMP 


The output listing might contain error messages, which describe errors that you may 
have made in specifying the AMDSADMP macro instruction. To respond to one of 
these messages, check your specification of the macro instruction and run the 
assembly step again. 


Note: Words shown here that begin with & are replaced in the error messages with 
the keyword values in error. 
CONSOLE PARM NOT DETECTED. DEFAULT (O1F, 3278) WILL BE USED. 
Explanation: Either the console parameter was not specified or it was not 
specified correctly on the continuation statement. The parameter was probably 
not continued correctly on the next defined statement. Continue the interrupted 
parameter or field beginning in any column from 4 through 16. 


(See JCL Reference. Read the topic covering ‘Continued Statements’.) 


Severity Code: 4. 


IPLUNIT WAS NOT SPECIFIED OR IPL= TYPE (D OR T) WAS SPECIFIED 
INCORRECTLY. UNIT WILL BE DEFAULTED TO SYSDA. 


Explanation: The IPL parameter should be specified as IPL=duuu, where ‘d’ is 
for D for direct access or T for tape, and ‘uuu’ is a valid unit type or address 
for the SADMP IPL volume as described by the UNIT = uuu JCL parameter. 


Severity Code: 0. 


IPL=&IPL IS INVALID. FIRST CHARACTER MUST BE D OR T, 
AND HAS BEEN REPLACED WITH A D. 


Explanation: The IPL operand is invalid. It is not prefixed with a 'D' ora 'T'. 


Severity Code: 4. 


- 


IPL=&IPL IS TOO LONG. THE UNIT NAME WILL BE TRUNCATED. 


Explanation: The unit name can be at most 8 characters long. 


Severity Code: 4. 
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CONSOLE ADDRESS &CONAD IS INVALID. IT MUST BE A DEVICE 


| NUMBER. @1F IS SUBSTITUTED. 


Explanation: The console address operand is not three hexadecimal digits. 


Severity Code: 4. 


CONSOLE TYPE &CONTP IS INVALID. IT MUST BE A 4 DIGIT 
NUMBER. 3278 HAS BEEN USED. 


Explanation: An invalid console type was specified. Only 3277, 3278, and 3279 
are acceptable. The length of the console type was not equal to 4. 


Severity Code: 4. 


| TYPE=&TYPE IS INVALID. IT MUST BE EITHER UNFORMATTED OR 


FORMATTED. TYPE=UNFORMATTED HAS BEEN USED. 
Explanation: Type operand must be HI, LO, UNFORMATTED, or FORMATTED. 


Severity Code: 4. 


TYPE=&TYPE CAN ONLY BE RESIDENT ON A DASD. A DASD 
RESIDENCE VOLUME HAS BEEN USED. 


Explanation: TYPE =LO and TYPE =FORMATTED can only be resident on a 
direct access device. 


Severity Code: 8. 


QUTPUT=&0UTPUT IS INVALID. IT MUST BE A T OR P FOLLOWED BY 
A DEVICE NUMBER. QUTPUT=PQ0E HAS BEEN USED. 


| Explanation: For TYPE =LO the output address was not prefixed with a ‘T’ or ‘P’ 


or the address was not a 3-character address. 


| Severity Code: 4. 


OUTPUT=&0UTPUT IS INVALID. IT MUST BE A T FOLLOWED BY 
A DEVICE NUMBER. OUTPUT=T282 HAS BEEN USED. 


Explanation: For TYPE =HI the output address was not prefixed by a ‘T’ or the 
address was not a 3-character address. 


Severity Code: 4. 


ULABEL=NOPURGE IS NOT POSSIBLE FOR A TAPE RESIDENCE VOLUME. 


Explanation: The ULABEL cannot be NOPURGE when the IPL device is tape. 


SADMP ignores your ULABEL specification. 


Severity Code: 8. 


ADDR=&ADDR IS INVALID. ADDR=REAL HAS BEEN USED. 
Explanation: The ADDR operand is not REAL or VIRTUAL. 


Severity Code: 4. 


MSG=8MSG IS INVALID. IT MUST BE ALL OR ACTION. 
MSG=ALL HAS BEEN USED. 


Explanation: The MSG operand is not ALL or ACTION. 


Severity Code: 4. 


LOADPT=&VALUE IS INVALID. X'1000' HAS BEEN USED. 


Explanation: The LOADPT operand must be a hexadecimal number from X'1000' 
to X'7FFFFFFF'. 


Severity Code: 4. 
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Initializing the Residence Volume 


You must make sure that the SADMP residence device does not contain a 
SYS1.PAGEDUMP data set if you are generating a direct access resident dump 
program. When SADMP finds a SYS1.PAGEDUMP data set on the direct access 
device to be initialized as the residence volume, initialization terminates. 


Execution of the stage-two JCL initializes the SADMP residence volume. The 
execution of this stage creates a SYS1.PAGEDUMP data set (on the residence 
volume) that contains the SADMP programs. 


Physical output from the assembly part of the initialization step is a listing for the 


SADMP central storage dump program, AMDSARDM. The remainder of the output 
consists of messages from the SADMP build module AMDSABLD and, when the 
residence volume is direct access, the device utility ICKDSF. 


One-Step Generation 
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The SADMP utility program, AMDSAOSG,, initializes a SADMP residence volume in 
one job step by dynamically allocating data sets and invoking the appropriate 
programs. To run the one-step generation program, indicate one AMDSADMP 
macro as a control statement for ddname GENPARMS, just as you would do on the 
SYSIN statement in the first stage of a two-stage generation. Figure 3-7 is asample 
job to generate SADMP in one job step: 


//SADMPGEN JOB MSGLEVEL=(1,1) 
//0SG EXEC PGM=AMDSAOSG 
//GENPARMS DD * 
AMDSADMP TYPE=HI,IPL=DSYSDA, VOLSER=SPOOL2, 


CONSOLE=(1A0,3277) — 
END 


7* 


Figure 3-7. Sample JCL for One-Step Generation of SADMP 


The output from AMDSAOSG is the same as the output from the residence volume 
initialization stage of two-stage generation, followed by a message from 
AMDSAOSG. AMDSAOSG returns the following codes: 


Message 


RESIDENCE VOLUME INITIALIZED 
RESIDENCE VOLUME NOT INITIALIZED DUE TO ERROR, OR A WARNING 


WAS ISSUED DURING AMDSADMP ASSEMBLY 


RESIDENCE VOLUME NOT INITIALIZED; GENPRINT COULD NOT BE 
OPENED 


AMDSAOSG allocates several ddnames for its own use and for use by the programs 
it calls. You can override these allocations by specifying DD statements in the 
AMDSAOSG job step. For example, when you want to: 


1. use a local modification of the AMDSABLD program in the cataloged load 
library SADMP.LOAD; and 


2. use a local modification of the AMDSADM2 macro in the cataloged macro 
library SADMP.MACLIB; and 


3. preserve the output listing in the cataloged data set SADMP.LIST 


you would code the JCL shown in Figure 3-8. 


//SADMPGEN JOB MSGLEVEL=(1,1) 
//0SG EXEC PGM=AMDSAOSG 
//STEPLIB DD DSN=SADMP.LOAD,DISP=SHR 
//SYSLIB DD DSN=SADMP.MACLIB,DISP=SHR 
DD DSN=SYS1.MACLIB,DISP=SHR 

//GENPRINT DD DSN=SADMP.LIST,DISP=OLD 
//GENPARMS DD * 

AMDSADMP TYPE=HI, IPL=DSYSDA, VOLSER=SPOOL2, X 

CONSOLE=(1A0,3277) 


END 
/* 


Figure 3-8. One-Step Generation With Overriding ddnames 
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Figure 3-9 (which has related notes that follow it) shows the ddnames AMDSAOSG 
uses, and the defaults for the ddnames. 


Figure 3-9. ddnames and Defaults Used by AMDSAOSG 


GENPARMS Must be preallocated. Input for AMDSAOSG, passed to 
assembler. 


GENPRINT SYSOUT=A | Output listing from AMDSAOSG 


IPLDEV DSN = SYS1.PAGEDUMP, UNIT = iplunit, SADMP program, output from AMDSABLD. 
VOL = (PRIVATE,SER = iplser), ICKDSF uses VOL keywords to describe 


the residence volume. 


DISP = OLD,DCB = (BLKSIZE = 12288, RECFM =U, 
DSORG = PS), LABEL = (,NL) 


DISP = (NEW,KEEP),DCB = (LRECL = 4096, BLKSIZE = 4096, 
RECFM = F,DSORG = PS),SPACE = (4096,(58), CONTIG), 
LABEL = EXPDT = 99366 


Tape IPL volume. 


DASD IPL volume. 


IPLTEXT DSN = SYS1.LINKLIB(AMDSAIPL),DISP = SHR Input for AMDSABLD. 
PGETEXT DSN = SYS1.LINKLIB(AMDSAPGE), DISP = SHR Input for AMDSABLD. 


AMDSAOSG, H assembler IEVS90, 
AMDSABLD and ICKDSF programs. This 
must be an APF-authorized library. 


STEPLIB 


SYSIN Must not be preallocated. 
| SYSLIB DSN = SYS1.MACLIB,DISP = SHR AMDSADMP and AMDSADM2 macros 
| DSN = SYS1.MODGEN,DISP = SHR 


SYSPRINT Must not be preallocated Temporary listings from called programs. 


Input for assembler and ICKSDF. 


| SYSPUNCH DSN = &OBJ, UNIT = SYSDA,SPACE = (80,(250,50)) | Object module passed from assembler to 
AMDSABLD 


SYSUT1 UNIT = SYSDA,SPACE = (1700,(50,50)) Work file for assembler 


TRKOTEXT DSN = &TRKOTEXT,UNIT = ipiunit, Cylinder 0, Track 0 IPL text from 
VOL = SER = ipiser, SPACE = (4096, (2,1)) AMDSABLD to ICKDSF 


Notes: 


1. To ensure that SADMP is available and successfully processes, the 
SYS1.PAGEDUMP data set should not be deleted or moved to another volume or 
pack. 


2. You must specify the GENPARMS ddname on the job step. 
3. You may not specify the SYSPRINT and SYSIN DD statements in the job step. 


4. In GENPARMS, you specify values for UNIT= and VOLSER= on the 
AMDSADMP macro statement. 
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Using One-Step Generation 
You must make sure that the SADMP residence device does not contain a 
SYS1.PAGEDUMP data set if you are generating a direct access resident dump 
program. When SADMP finds a data set on the device to be initialized as the 
residence device, initialization terminates. 


Execution of AMDSAOSG initializes the SADMP residence volume. The execution of 
the SADMP utility program creates a SYS1.PAGEDUMP data set (on the residence 
volume); this data set contains the SADMP program. 


Physical output from the assembly part of the initialization step is a listing for the 
SADMP central storage dump program AMDSARDM. The remainder of the output 
consists of messages from SADMP build modules AMDSAOSG and AMDSABLD, and 
when the residence volume is direct access, the device utility ICKDSF. 


Dumping Additional Storage 


You can request that SADMP dump additional storage by specifying dump tailoring 
options, either when the SADMP residence volume is initialized, or at execution 
time. For instance, you may want to request more storage to retrieve information 
from a user address space. 


Requesting Additional Storage During SADMP Generation 


Indicate the dump tailoring options described in “Dump Tailoring Options” on 
page 3-20 within parentheses and single quotes as the value of the DUMP keyword 
on the AMDSADMP macro. 


Examples: 


DUMP=('SP(5,37,18) IN ASID('JES3')') 
DUMP=('RANGE(@:1000000) IN ASID(1)') 
DUMP=('DATASPACES OF ASID('RASP') ') 


Note: Do not double the quotes within the DUMP options. The DUMP options may 
not exceed 255 characters in length. 


Requesting Additional Storage During SADMP Execution 


By coding the PROMPT keyword on the AMDSADMP macro, you can have SADMP 
prompt the operator to dump additional storage during execution. When you code 
PROMPT = YES, and the virtual storage dump program gets control, it issues the 
following message: | 


AMDQ59D ENTER ‘DUMP’ OR 'SET' WITH OPTIONS, ‘LIST’ OR ‘END’. 


The operator responds with one of the following: 
1. DUMP followed by dump options. In this case, the ‘=’ after DUMP ts optional. 
2. SET followed by the MINASID options. 


3. LIST. On the console, SADMP displays the current virtual storage areas to be 
dumped. 


4. END. SADMP stops prompting the operator for options and begins processing. 


When SADMP detects an error in the dumping command, it repeats the incorrect 
line at the console, underscores the invalid part with ‘*’s, and prompts the operator 
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for replacement text. When the dump command input is longer than 255 characters, 
SADMP marks the whole line in error. 


A system restart during the virtual storage dump program causes SADMP to 


_reprompt the operator for dump options. SADMP does not use any of the dump 


options that the operator specified before the system restart. 


Figure 3-10 shows a sample exchange between SADMP and the operator. The 
operator’s replies are in lowercase. | 


AMDQ82I WARNING: THE MINASID SPECIFICATION HAS BEEN SET TO 'PHYSIN'. 
AMDO59D ENTER 'DUMP' OR 'SET' WITH OPTIONS, 'LIST' OR ‘END'. 
dump sp(0::9) inasid('jes2') : 
AMDO60I ERROR IN INPUT TEXT INDICATED BY '*': 
DUMP SP(0::9) INASID('JES2') 
* 


AMDO65A ENTER TEXT TO BE SUBSTITUTED FOR THE TEXT IN ERROR. 
> 
AMDOQ60I ERROR IN INPUT TEXT INDICATED BY '*': 
DUMP SP(0:9) INASID('‘JES2') 
RK aK 
AMDO65A ENTER TEXT TO BE SUBSTITUTED FOR THE TEXT IN ERROR. 
> in asid 
AMDQ82I WARNING: THE MINASID SPECIFICATION HAS BEEN SET TO 'PHYSIN'. 
AMDO59D ENTER 'DUMP' OR 'SET' WITH OPTIONS, 'LIST' OR 'END'. 
> list : 
AMDO0671I CURRENT DUMP OPTIONS: 
CSA ALSO LSQA, SP(203:205,213:215,229:230,236:237,247:248) IN ASID(PHYSIN) 
ALSO SP(0:9) IN ASID('JES2') 
AMDO821 WARNING: THE MINASID SPECIFICATION HAS BEEN SET TO 'PHYSIN'. 
AMDO59D ENTER 'DUMP' OR 'SET' WITH OPTIONS, 'LIST' OR 'END'. 
> end 
AMDO10I PROCESSING ASID=0001 ASCB=00FDAFOO JOBNAME=*MASTER* 


Figure 3-10. Sample Exchange Between SADMP and the Operator 


Dump Tailoring Options 
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You request additional storage that you want dumped by specifying address ranges, © 
subpools, or LSQA in a list of address spaces when you reply to the message: 


AMDO59D ENTER 'DUMP' OR 'SET' WITH OPTIONS, ‘LIST' OR 'END'. (asin Figure 3-10) 


RANGE(qualifier) IN ASID(qualifier) 
SP(qualifier) 

LSQA = 
{DATASPACES|DSP} OF ASID(qualifier) 
{PAGETABLES OF DATASPACES} | 


_ The above example specifies one or more ranges of storage addresses, subpools, 


or LSQA that you want dumped from particular address spaces that you specify as 
ASIDs, jobnames, or TCB system keys. The example also requests dumping of user 
data spaces owned by specific address spaces and RSM data spaces. You can 
extend this syntax by combining parts into lists. See “SADMP DUMP Command 
Syntax” on page 3-23. | 


RANGE Option 


SP Option 


ASID Option 


When you specify RANGE, SADMP dumps all pages within the address range that 
you specify. You can specify RANGE as any of the following: 


RANGE(Xxxx:yyy,Xxx:yyy...) 
specifies one or more ranges of storage that you want dumped. xxx and yyy are 
hexadecimal addresses from 0 to X'7FFFFFFF ' 


RANGE(ALL) 
specifies dumping of all storage from 0 to X'7FFFFFFF' 


When you specify SP, SADMP dumps only the storage allocated to the subpools that 
you specify. You can specify SP as any of the following: | 


SP(ddd) 
causes SADMP to dump subpool ddd. ddd is a decimal integer from 0 to 255. 


SP(ddd:eee) 
causes SADMP to dump all subpools from ddd to eee, inclusive. 


SP(ddd:eee,ddd:eee.,...) 
causes SADMP to dump the combination of subpools that you specify. 


SP(ALL) 
causes SADMP to dump all subpools, from 0 to 255 inclusive. 


LSQA 
causes SADMP to dump the LSQA. 


You can specify ASID as any of the following: 


ASID(xxx:yyy) 
causes SADMP to dump storage for the range of address spaces whose address 
space identifiers begin at xxx and end at yyy, inclusive. xxx and yyy are 
hexadecimal numbers from X'1' to X'FFFF'. 

ASID(‘jjj’) 
causes SADMP to dump storage for the address space that jobname jjj 
identifies. Note that you must enclose the jobname in single quotes. 


ASID(SYSKEY) 
causes SADMP to dump storage for all address spaces whose active TCB has 
an associated storage key of 0 to 7. 


ASID(combination) 
You may combine any of the above specifications. An example of a valid 
combination is ASID(2,‘IMSJOB’,SYSKEY). 


ASID(PHYSIN) 


causes SADMP to dump storage for physically swapped-in address spaces. 


ASID(ALL) 
causes SADMP to dump storage for all address spaces. Note that you cannot 
specify ASID(ALL) in combination with any of the other ASID specifications. 
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DATASPACES Option 


DATASPACES OF ASID(qualifier) 
When you specify the DATASPACES OF AS1D (qualifier) keyword, SADMP dumps 
all data spaces owned by the specified address space. For each requested data 
space, SADMP: | 


° Dumps pages backed by central storage during the central storage dump. 


¢ Copies into central storage and dumps every page that is not a first 
reference page and not backed by central storage 


PAGETABLES OF DATASPACES 
When you specify the PAGETABLES OF DATASPACES keyword, SADMP dumps 
paged-out virtual storage that contains the page tables for all data spaces. 


When SADMP dumps the storage that you specify, SADMP dumps all listed subpools 
and address ranges in all specified address spaces for each specification of dump 
options. However, SADMP does not merge your specifications across the dump 
options that you specify. For example, 


DUMP SP(0,1) IN ASID(A,B) 


causes SADMP to dump subpools 0 and 1 in address space A, and subpools 0 and 1 
in address space B. 
DUMP SP(Q) IN ASID(A) ALSO SP(1) IN ASID(B) 


causes SADMP to dump subpool 0 in address space A and subpool 1 in address 
space B. | 


Specifying The Minimal SADMP 


You can request SADMP to dump certain system related storage ranges in all 
address spaces that are physically swapped-in at the time the dump is taken. 


Requesting The Minimal Dump Option 
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Use the MINASID keyword on the AMDSADMP macro to specify the minimal dump 

option. If MINASID is not specified on the AMDSADMP macro invocation, the default 
of MINASID=ALL is assumed. You can also use the new command SET MINASID in the 
SADMP dialogue if you requested prompting on the AMDSADMP macro invocation. 


If you specify MINASID=ALL on the AMDSADMP macro invocation, or MINASID is 
omitted, or if you enter SET MINASID(ALL) in the SADMP dialogue, the minimal dump 
will include: 


DUMP CSA ALSO LSQA, SP(203:205,213:215,229:230,236:237,247:248) IN ASID(ALL) 


If you specify MINASID=PHYSIN on the AMDSADMP macro invocation, or if you enter 
SET MINASID(PHYSIN) in the SADMP dialogue, the minimal dump will include: 


DUMP CSA ALSO LSQA, SP(203:205,213:215,229:230,236:237,247:248) IN ASID(PHYSIN) 


Figure 3-11. Requesting The Minimal Dump Option During SADMP Generation 


AMDO59D ENTER 'DUMP' OR 'SET' WITH OPTIONS, ‘LIST’ OR 'END'. 


>set minasid(physin) 


Figure 93-12. Requesting The Minimal Dump Option During SADMP Execution 


SADMP DUMP Command Syntax 


dump-command 


DUMP [ = ] dump-spec-list 

SET MINASID(ALL | PHYSIN) 

LIST | 

END 

range-spec-list IN domain-spec-list [ ALSO... ] 
{DATASPACES | DSP} OF domain-spec-list [, ...] 
PAGETABLES OF DATASPACES 

(dump-spec-list) 
{SP(subpool-list)|RANGE(address-range-list)|LSQA}T,... ] 
::= (range-spec-list) 


dump-spec-list 


range-spec-list 


subpool-list ::= subpool-number TO subpool-number [,... ] 
= ALL 
address-range-list = address TO address f.... ] 
= ALL 
domain-spec-list ::= ASID(address-space-list)|,... ] 
::= (domain-spec-list) 
address-space-list ::= {asid TO asid|jobname|SYSKEY|PHYSIN}{,... ] 
= ALL 


where 


address is a hexadecimal number from 0 to X'7FFFFFFF' 
subpool-number is a decimal number from 0 to 255 

asid is a hexadecimal number from 0 to X'FFFF' 

jobname is a valid jobname enclosed in single quotes 
range-spec-list is a list of subpools, a list of storage ranges, or both 
domain-spec-list is a list of address spaces 

‘TO’ and ‘:’ are synonyms 

‘DATASPACES’ and ‘DSP’ are synonyms 


You may truncate keywords, such as DATASPACES, on the right, provided the 
truncated form is unambiguous. You may enter letters either in lower or upper 
case. You may insert blanks between numbers, keywords, and separators; you may 
not insert blanks within numbers or keywords. 


The following are examples of valid specifications: 


DUMP SP(0:7,15) ,RANGE(Q:10000000) IN ASID(SYSKEY) ,ASID(8) 

DU (SP(O TO 7 OR 15),SP(255)) IN AS('TCAM') 

DUMP RANGE(ALL) IN ASID(1) ALSO SP(@) IN ASID(SYSKEY,8) 

DU DAT OF AS(ALL) | 

DUMP ( SP(0:127) IN ASID('GENER') ALSO SP(0) IN ASID(‘IMS') ) 
DUMP LSQA IN AS('MYJOB' ,14) 

DU SP(128),LS IN ASID(C,PHYSIN) 
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Executing SADMP 
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This section describes four procedures for executing SADMP: 


e Initialization and execution 
e Restart 

e Reinitialization 

e¢ Dumping 


Procedure A: IPLing and Executing SADMP: Use procedure A to IPL the SADMP 
program and dump storage. If you want to rerun SADMP, for instance when SADMP 
fails, use procedure B, procedure C, or procedure D. 


Procedure B: Restarting SADMP: When you want to rerun SADMP, use procedure B 
(restart) before you try procedure C (re-IPL that dumps MVS) or procedure D (new 
IPL that dumps SADMP). Procedures C and D can result in the loss of some central 
storage from the output, whereas procedure B usually does not. 


However, a system restart cannot always work, either because it occurs at a point 
when SADMP internal resources are unserialized, or because SADMP has been too 
heavily damaged to function. If the restart does not work, try procedure C (re-IPL). 


If SADMP terminates abnormally while dumping central storage (before message 
AMDOO5I appears), try to restart SADMP by performing procedure B. If the restart 
succeeds, SADMP reruns the entire dump. It will first enter wait state X'140000' to 
allow you to specify a new console and output tape. You can do this to recover from 
a terminating I/O error on the output tape. 


Messages AMDO05I and AMD010I indicate that SADMP is beginning to dump virtual 


storage. If you cause a system restart at this time, SADMP redumps only the | 
paged-out virtual storage. Do not issue a system restart if the previous output tape 
has been rewound and has not been replaced with a new one. 


The maximum number of times that you can restart the virtual storage dump 
program is two. 


Procedure C: RelPLing SADMP: When you re-IPL SADMP, the previous execution 
of SADMP has already overlaid some parts of central storage and modified the page 
frame table. 


lf the virtual storage dump program was in control, a re-IPL may not dump 
paged-out virtual storage. The number of times that you can IPL SADMP to dump 
paged-out virtual storage is equal to the number of processors present. 


_ Procedure D: Dumping SADMP: Use a new IPL of SADMP to debug SADMP if 


SADMP fails. The self-dumps and system restart are two features of SADMP error 
recovery. When errors occur during virtual storage dump execution, SADMP can 


take a maximum of two self-dumps. You can use these to diagnose SADMP 


processing errors. The SADMP system restart capability also assists you in testing 
and debugging SADMP. 


Self-Dumps: During virtual storage dump execution, when SADMP error recovery 
cetects errors in SADMP, SADMP may take a self-dump before proceeding. At 
most, SADMP takes two self-dumps; on the third request for a self-dump, module 
AMDSAAUD terminates SADMP processing. SADMP places both the self-dump and 
the operating system dump onto the output tape. 


You can use the LIST subcommand of IPCS to print SADMP self-dumps. The format 
of the subcommand is: 


LIST address COMPDATA(AMDSAQOQx) where x = 1 or 2 


For complete information on using the LIST subcommand of IPCS, see IPCS 
Command Reference. 


System Festart: SADMP has a built-in system restart capability that assists you in 
testing and debugging SADMP. By causing a system restart, you can reinitialize 
and restart a failing SADMP program. For a virtual storage dump program, you can 
restart SADMP at most twice. 


Procedure A: IPLing and Executing SADMP 


1. 
2. 
3. 


Use the global STOP function to STOP all processors. Do not clear storage. 
Select a processor that was on-line when you stopped the system. 


If the processor provides a function to IPL a stand-alone dump without 
performing a manual STORE STATUS, use this function to IPL SADMP. lf you do 
not use such a function, perform a STORE STATUS before IPLing stand-alone 
dump. 


Note 
Do not use the LOAD CLEAR option. If the LOAD CLEAR option is used, main 


storage is erased and the dump data set will contain invalid information. 


. Mount the volume that contains the stand-alone dump program on a device 


attached to the selected processor; ready the device. 


Note: If this is a tape volume, make sure that the file-protect ring is in place. If 
itis a disk volume, make sure it is write-enabled. 


. IPL SADMP. 


SADMP does not communicate with the operator console. Instead, SADMP 
loads an enabled wait PSW with wait reason code X'140000'. 


Note: SADMP is waiting for a console I/O interrupt or an external interrupt. 


. Identify the console and output device. Select one operator console whose 


device address is in the console list that you specified at SADMP generation 
time. Cause that console to generate an interruption. Depending on the type of 
console, pressing one or more of the following keys will generate the required 
interrupt: ATTENTION, CLEAR, ENTER, or SYSTEM REQUEST. (On some 
consoles, you might have to press RESET first.) This interruption informs 
SADMP of the console’s address, and SADMP responds with message 
AMDOOT1A. 


a. Ready an output device. For tapes, make sure that the tape is initialized 
with a tape mark and the file protect ring is inserted. Reply with the 
three-digit address of the device. If the device is the default that you 
specified at SADMP generation time, then press ENTER instead of providing 
the three-digit device address. 


Note: If you reply with the address of an attached device that is not the 
required device type, or if the device causes certain types of I/O errors, 
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SADMP might load a disabled wait PSW with wait reason code X'150900'. 
When this occurs, use procedure B to restart SADMP. 


b. SADMP prompts you, with message AMDO45A, to specify whether or not you 
want to write over the existing label on a labeled tape. 


c. SADMP prompts you, with message AMD011A, for a dump title. 


d. For formatted dumps, SADMP issues message AMDOO08A. Respond with R 
for real or V for virtual, followed by the address range that you want 
dumped. Specify addresses that are eight hexadecimal digits in length. 
When the output device is a tape, SADMP dumps storage for the address 
range that you specify. When the output device is a printer, SADMP 
reprompts the operator with message AMDOO8A. 


7. When no console is available, you can run SADMP without a console by 


10. 


aE: 


12. 


Service Aids 


entering a null response to AMDOO1A: 


a. Determine the device address that you specified as the default output 
address (in the OUTPUT parameter on the AMDSADMP macro) during 
SADMP residence volume initialization. To execute SADMP, you must 
define this address to the processor. Ready this device. For tapes, ensure 
that the file protect ring is in. 


b. Enter an external interruption on the processor that SADMP was IPLed from. 
_SADMP proceeds using the default output device. No messages appear on 
any consoles; SADMP uses PSW wait reason codes to communicate to the 

operator. 


. When TYPE =LO and the output device is a tape, SADMP loads a wait PSW with 


wait reason code X'410000' after completing the dump. This PSW indicates 
normal termination of SADMP. 


. When SADMP finishes dumping central storage, it issues message AMDOOSI. 


SADMP may terminate at this step. 


a. When message AMDO68lI appears, followed by wait reason code X'150200', 
SADMP is unable to dump paged-out virtual storage, so SADMP unloads the 
tape and stops processing. This is normal termination of SADMP when: 


e The system being dumped was at an early stage of initialization, or 
e The system being dumped was not MVS/ESA, or 
e No STORE STATUS was performed. 


b. Wait reason codes equal to X'25xxxx' are normal when MVS/ESA was not 
fully initialized. SADMP does not unload the output tape, but it has written 
an end-of-file. 


If you specified PROMPT on the AMDSADMP macro, SADMP prompts you for 
additional storage that you want dumped by issuing message AMDO59D. 


SADMP dumps instruction trace data, paged-out virtual storage, and the SADMP 
message log. 


When SADMP completes processing, SADMP unloads the tape and enters a wait 
reason code X'410000'. 


Procedure B: Restarting SADMP 


1. Enter a system restart on the processor that you IPLed SADMP from. 


2. If the restart is successful, SADMP backs up to a certain point, and continues as 
in procedure A. During the central storage dump, a system restart causes 
SADMP to reenter wait reason code X'140000'. During the virtual storage 
dump, a system restart causes SADMP to repeat the virtual storage dump. 


3. Continue procedure A. If you restarted SADMP during the central storage dump 
program, continue procedure A at step 5. If you restarted SADMP during the 
virtual storage dump program, continue procedure A at step 9. 


Procedure C: RelPLing SADMP 


1. Repeat procedure A, but do not issue a STORE STATUS. When you are IPLing 
using a stand-alone dump hardware function, the STORE STATUS is omitted 
from all IPLs of SADMP after the first IPL. If the previous IPL of SADMP did not 
load a wait state and reason code of X'250000' or higher and the reiPL 
succeeds, SADMP usually completes processing as in procedure A. Some 
storage locations might not reflect the original contents of central storage 
because, during a previous IPL, SADMP overlaid the contents. These locations 
include the absolute PSA and possibly other PSAs. 


Procedure D: Dumping SADMP 


When you use SADMP to dump itself, you specify either an unformatted (high-speed) 
SADMP, or a formatted (formatted) SADMP to a printer. 


1. Record all messages and wait state and reason codes from the failed SADMP. 
2. Select a high-speed or a formatted dump. 
For a high-speed dump, do the following: 
a. Perform a STORE STATUS. 
b. Do procedure A. 
For a formatted dump, do the following: 


a. (Optional) Instead of examining the printed dump in steps e and f that follow, 
you can inspect central storage to determine which addresses to dump. 


b. Perform a STORE STATUS. 
c. Do procedure A. 


d. Respond ‘R,00000000:00000FFF’ to message AMDOO8A. This dumps real 
page 0. 


e. Examine the printed output from step d. Respond ‘R,aaaaaaaa:bbbbbbbb’ 
to message AMDOO8A, where aaaaaaaa is the contents of the fullword at 
location X'208' and bbbbbbbb is the contents of the fullword at location 
X'20C'. This dumps the failed central storage dump program, if the central 
storage dump program was in storage at the time of the failure. 


f. Examine the printed output from step d. cccccccc is the contents of the 
fullword at location X'244'. If ccccceccc equals X'00000000', then do not 
continue trying to dump SADMP. If cccccccc is non-zero, dddddddd equals 
cccccccc plus X'80000'. Respond ‘V,cccccccc:dddddddd’ to message 
AMDOO8A. This dumps the virtual storage dump program that failed. 


3. Save the original SADMP output as well as the dump of SADMP. 
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Messages and Operator Communications During Execution 
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After IPL, SADMP enters an enabled wait state and reason code of X'140000' to wait. 
for operator communication. Select one of the consoles whose address you 
specified on the CONSOLE = keyword, and press ENTER at that console. On some 


~consoles, you may have to press RESET before you press ENTER. If no console is 


available, enter an external interruption. The dump program then bypasses 
operator communication and attempts to dump storage to the unit that you specified 
in the OUTPUT = keyword. 


If the dump output is directed to tape, you receive this message: 


AMDOO1A ENTER ADDRESS OF OUTPUT TAPE. 


After readying the tape that you want to use, enter the tape’s three-character 
hexadecimal address. When you press ENTER and do not enter an address, SADMP 
uses the address that you specified on the OUTPUT == keyword. 
SADMP looks at the tape label, if one is present, for indication of protection. If the: 

e ‘security’ code, in the case of an ‘IBM Standard Data Set Label 1’, or the 

e ‘accessibility’ code, in the case of an ‘ANSI Standard Data Set Label 1’, 
indicates that the tape is ‘protected’ by either standard, then SADMP does not read 
the tape. 


If the tape is not protected, SADMP issues this message: 


AMDQ45D TAPE LABEL=vvvvvv. REPLY 'USE' or 'UNLOAD'. 


where vvvvvv is the volume serial number. Reply USE to write over the label and 
use the tape. When you reply UNLOAD, SADMP unloads the tape and issues the 
following message: 


AMDO51A MOUNT ANOTHER TAPE. 


Continue until a suitable tape is mounted. 


If the dump output is directed to a printer, you receive this message: 


AMDQ01A ENTER ADDRESS OF PRINTER. 


You can use the printer that you specified in the macro instruction, or you can 
specify a different printer. 


After you specify the output device, SADMP issues message AMD011A to prompt 


— you for a dump title. 


AMDO1IA TITLE= 


You can specify a title of up to 100 characters. The dump title appears at the top of 

each page of output that SADMP formats, or at the top of each page of unformatted 

output after IPCS formats the output. You should select a title that explains why the 
dump was taken. 


For the formatted (formatted) dump program, SADMP prompts for a real or virtual 
address range to dump after processing the dump title. SADMP issues the following 
message: 


AMDOO8A ENTER ADDRESS RANGE. "R,NNNNNNNN:MMMMMMMM" 


You must specify ‘R’ (real addresses) or ‘V’ (virtual addresses) followed by an 
eight-digit hexadecimal starting address, °:’, and an eight-digit hexadecimal ending 
address. For example, ‘R,000070000:00007FFFF’ and ‘V,00C00000:01800000’ are 
valid specifications. Before dumping, SADMP rounds the starting address down to 
the closest 4K boundary, and rounds the ending address up to the closest 4K 
boundary. 


When the formatted (formatted) dump output is directed to tape, SADMP dumps only 
One storage range. When the formatted dump is directed to a printer, SADMP 
reprompts the operator for address ranges. 


When SADMP completes the dump of central storage, SADMP issues this message: 


AMDQO5I DUMPING OF REAL STORAGE COMPLETED. 


After completion of the central storage dump program, the high-speed dump 
program starts to dump console trace data and paged-out virtual storage. 


If you specified PROMPT on the AMDSADMP macro, SADMP prompts the operator 
for additional virtual storage to dump by issuing the following message: 


AMDO59D ENTER 'DUMP' OR 'SET' WITH OPTIONS, 'LIST' OR ‘END’. 
(as in Figure 3-10 on page 3-20) 


See “Requesting Additional Storage During SADMP Generation” on page 3-19 for 
the format and meaning of your reply to this message. 
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When the console screen is full with messages, SADMP issues this message: 


AMDO29D REPLY W TO WAIT AFTER NEXT FULL SCREEN, ELSE 


REPLY N; REPLY= 


When you reply W, SADMP erases the screen and writes message AMDO029D again 
the next time the screen is full. When you reply N, SADMP erases the screen 
whenever the screen is full, and does not issue message AMDO29D again. 


To terminate the virtual storage dump program before the dump would ordinarily 
end, cause an external interruption on the processor that SADMP is executing on. 


The following is a sample exchange between SADMP and the operator during 
execution of an unformatted SADMP program. The operator’s replies are in © 
lowercase. 


AMDOO1A ENTER ADDRESS OF OUTPUT TAPE. 571 
AMDO11A TITLE= sample dump. 
AMD045D TAPE LABEL= 175638. REPLY 'USE' OR 'UNLOAD'. use 
AMDOO5I DUMPING OF REAL STORAGE COMPLETED. 
AMDOQ82I WARNING: THE MINASID SPECIFICATION HAS BEEN SET TO 'PHYSIN'. 
AMDO59D ENTER ‘DUMP’ OR 'SET' WITH OPTIONS, 'LIST' OR 'END'. 
> set minasid(al1) 
AMDO59D ENTER 'DUMP' OR 'SET' WITH OPTIONS, 'LIST' OR ‘END’. 
> dump sp(all) in asid('jes2') 
AMDO59D ENTER 'DUMP' OR 'SET' WITH OPTIONS, ‘'LIST' OR 'END'. 
dump dataspaces of asid('dumpsrv') | 
AMDO59D ENTER 'DUMP' OR 'SET' WITH OPTIONS, 'LIST' OR 'END'. 
> list 
AMDOQ67I CURRENT DUMP OPTIONS: 
CSA ALSO LSQA, SP(203:205,213:215,229:230,236:237,247:248) IN ASID(ALL) 
ALSO SP(ALL) IN ASID('JES2') 
ALSO DATASPACES OF ASID('DUMPSRV') | 
AMDO59D ENTER 'DUMP' OR 'SET' WITH OPTIONS, 'LIST' OR 'END'. 
> end 7 
AMDO10I PROCESSING ASID=0001 ASCB=OOQFDAFOO JOBNAME=*MASTER* 
AMDO1O1 PROCESSING ASID=0002 ASCB=00F24400 JOBNAME=PCAUTH 
AMDO1OI PROCESSING ASID=0003 ASCB=00F24180 JOBNAME=RASP 
AMDO10I PROCESSING ASID=0004 ASCB=Q0FOAEOO JOBNAME=TRACE 
AMDQ101I PROCESSING ASID=0005 ASCB=00FOQACOQ JOBNAME=GRS 
AMDQ571 COMPLETED SPECIFIC DUMPING FOR GRS 
AMDOQ10I. PROCESSING ASID=0006 ASCB=00F27E00 JOBNAME=DUMPSRV 
AMDQ76I PROCESSING DATA SPACE SDUMPCSA, OWNED BY ASID 0006. 
AMDO10I PROCESSING ASID=0008 ASCB=00F40E00 JOBNAME=CONSOLE 
AMD081I ASID 0009 NOT DUMPED, PHYSICALLY SWAPPED OUT (JOBNAME=INIT 
AMDOQ10I PROCESSING ASID=000A ASCB=00FQAA00 JOBNAME=SMF 
AMDQ@81I ASID O00B NOT DUMPED, PHYSICALLY SWAPPED OUT (JOBNAME=INIT 
_ AMDQ81I ASID QOOC NOT DUMPED, PHYSICALLY SWAPPED OUT (JOBNAME=INIT 
AMDO029D REPLY W TO WAIT AFTER NEXT FULL SCREEN, ELSE REPLY Ns REPLY= w 


SADMP also communicates to the operator using wait state and reason codes. See 
System Codes. 
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SADMP Messages on the 3480 Display 


When stand-alone dump output is sent to a 3480 magnetic tape subsystem, SADMP 
uses the subsystem’s eight-character message display to inform and prompt the 
operator. The leftmost position on the message display indicates a requested 
operator action. The eighth position (rightmost) gives additional information. 


The SADMP messages that can appear on the 3480 display are: 


Dvolser (alternating) 
MSADMP#U 
informs the operator that a labeled tape has been rejected and a new tape must 
be mounted. 
MSADMP#U (blinking) 
requests that the operator mount a new tape. 
RSADMP#U (blinking) 
indicates that the SADMP program has finished writing to the tape. 
RSADMP# (alternating) 
MSADMP#U 


informs the operator that an end-of-reel condition has occurred and a new tape 
must be mounted. 


SADMP# (blinking) 
indicates that the tape is in use by SADMP. 


SADMP# (alternating) 
NTRDY 
informs the operator that some type of intervention is required. 


The symbols used in the messages are: 


# 
is the actual number of reels SADMP has mounted. It is a decimal digit 
starting at 1 and increasing by 1 after each end-of-reel condition. When 
the # value exceeds 9, it is reset to 0. 

D 
means to demount the tape and retain it for further system use, for 
example as a scratch tape. SADMP does not write on the tape. 

M 
means to mount a new tape. 

R 
means to demount the tape and retain it for future SADMP use. 

U 
means the new tape should not be file-protected. 

volser 


is the volume serial number on the existing tape label. 
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SADMP Output 


The format of SADMP output depends on the version of the stand-alone program 
that generated it. 7 


Unformatted Output 


Unformatted SADMP output must be displayed at a terminal or printed using IPCS. 
For full information, refer to the /PCS User’s Guide. 


Use the SADMPMSG verb name of the IPCS VERBEXIT subcommand to format and 
print the SADMP message log, or, using IPCS, view the message log on the screen. 
See the /PCS User’s Guide for details. 


Formatted Output 


If you direct formatted dump output to a printer, you can immediately use the output 
as a diagnostic aid. Figure 3-13 shows an example of SADMP formatted output 
directed to a printer. The IEBPTPCH and IEBGENER utilities can be used to print 
SADMP output. Figure 3-14 on page 3-34 shows how to use IEBPTPCH to print 
SADMP output. For information on using IEBGENER, see the publication Utilities. 


You can also use IEBPTPCH to display the contents of a SADMP output on tape. You 
can code your JCL so that IEBPTPCH displays all or selected SADMP output 
records, and displays each record totally or partially. Figure 3-15 on page 3-34 © 
shows how to use IEBPTPCH to print portions of a SADMP output tape. 


Copying SADMP Output 
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You can copy SADMP output from tape to a DASD data set. Figure 3-16 on 
page 3-34 shows how to use IEBGENER to copy tape output to DASD. Two- 
advantages from copying SADMP tape output to DASD are: 


e When SADMP terminates prematurely and does not give the SADMP output 
(SYSUT1) an end-of-file, the SYSUT2 data set does contain an end-of file. 
(SYSUT2 is the data set to which SADMP output is copied.) This occurs even 
when SYSUT2 is another tape. IEBGENER might end with an I/O error on 
SYSUT1; this is normal termination if SYSUT1 does not contain an end-of-file. 


e When SYSUT2 is a direct access data set and you use it as input for IPCS, this 
saves IPCS processing time. 


weil es >>> SAMPLE LOW SPEED (FORMATTED) SADMP OUTPUT 
00D21000 


CURRENT PSW 


t 
™“ 


TAMTMOOO YP OY |D 


AWDDDAD ADD DA 
ee OO OO 


00000000 
00000020 
00000040 
00000060 
00000080 
QOCOO0A0 
00000000 


V 
V 
V 
V 
V 
V 
V 


FFFFFFFC 
00000000 
00000000 
00000000 
5EB1EE40 
00000000 
00000000 
00000000 


90000004 
00000000 
O1FO1FB8 
90000000 
0051207F 
0000000 
00000000 
00000000 


Q00COO0O8OD1F1DO 


7FFEFOQO 
00000000 
O1FO1E20 
00000000 
002E3D40 
00000000 
00000000 
00000000 


PREFIX 


7FFEFQOO 
00010003 
O1FO2E1F 
00000000 
8000000C 
00000000 
00000000 
00000000 


STORAGE KEY OE 

Q040C0000 81116CA8 
071C0000 80015C38 
00000000 00000000 
040C0000 80FEZE00 
00000000 00001004 
03000000 0101CE08 
00000000 00000000 


PRINTING OF DUPLICATE LINES 


00000200 
00000220 
00000240 
00000260 
00000280 
Q00002A0 
000002CO 
Q000002E0 
00000300 
00000320 


V 
V 
V 
V 
V 


V 
V 
V 
V 
V 


D7E2C140 00010041 
OO0F34200 OOF 34200 
00000000 00000000 
ADQ70950 ADOQ00950 
QOFD8C78 00000000 
00000000 00000000 
00000000 OOFD8CDO 
00000000 00000000 
QOFC5D98 00000000 
Q000000O COOQNDOO 


PRINTING QF DUPLICATE LINES 


00000360 
00000380 
000003A0 
000003C0 
000003E0 
00000490 
00000420 
00000440 
00000460 
00000480 
Q00004A0 


V 
V 
V 
V 
V 
V 
V 
V 
V 
V 


V 


00000000 
G0000C00 
QOF 2F560 
00000000 
90000000 
040CE000 
070C0000 
000090000 
00000000 
00000000 
00000007 


00000000 
e0000coO 
00000CEO 
00000000 
00000000 
SOFE3F36 
SOFEDA62 
00000000 
00000000 
00000000 
00000000 


00000000 
070D6000 
00000000 
000CO000 
00020072 0006002B 
00000000 Q0000000 
00000000 00000000 
WAS SUPPRESSED. 

QOFOCO08 OOCDEDOS 
00000000 00000000 
00000000 01129E90 
ADQ40950 ADO70950 
QOFD8C80 00009000 
QOFD8C88 00000000 
00000000 QO000000 
090000008 00000000 
5EB10200 00040000 
00000000 HO000000 
WAS SUPPRESSED. 

00000000 90000000 
QOFZE370 QO000COD. 
QOF2FE58 OOF2F560 
00000000 00000000 
00000000 90900000 
00000000 00000000 
00000000 00000000 
00000000 00000000 
Q070D6000 81FOOE5E 
00000000 00000000 
90000000 00000000 


00000000 
81FOOE5E 
OO0FD8460 
80D1F1D0 


00010003 
00000000 
81FO09F8 
00000000 
Q000000C 
0005223B 


QOFD8460 
00000000 
00000000 
00080000 
7FFE4003 
00000000 
00000000 


OOF 2B000 
00000000 
04000000 
ADOQ70950 
00000000 
OOFD8CCO 
QOFD8CC8 
00000000 
00000000 
00000000 


00000000 
Q1AB1108 
00F30750 
01AB0810 
8007D000 
Q1AACFD8 
00000000 
00000000 
00000000 


OOFF5768 
00000000 
01FO1E20 
90000000 
00090300 
0051207F 


00000000 
00000000 
00000000 
80D203A8 
00000000 
00000000 
00000000 


0OCFCOQO0 
00000000 
OOFE4FO0 
00000000 
90000000 
00000000 
GOFD8CD8 
00000041 
00000000 
00000000 


00000000 
00000000 
00000000 
00000000 
581003F0 
01A94C90 
00000000 
90000000 
035E1A00 


CPU ID 
OOACSFF8 
00000000 
0000000D 
00000000 
FEOQ0000 
DF880C6B 


070C0000 
070C0000 
04000000 
040C0000 
O1FOOED5E 
00010000 
00000000 


QOAEAA58 
00000000 
040COQ000 
00000704 
00000000 
00000000 
OOFD8CEO 
00000000 
00000001 
00000000 


QOQ00BOE 


0001 
FDOQ0000 
00000000 
00000000 
00000000 
0051207F 
7FFE4QBO 


80FE3076 
811F350C 
8110ACD8 
8101CF00 
00000000 
00F 69270 
00000000 


QOAEAA58 
00000072 
80039D5C 
00000000 
00000000 
00000000 
00000000 
OOFEFBBO 
QOFFEQ7F 
00000000 


QBQEO00O 


OOFZEC68 OO000C00 
Q1AB1A00 00000000 
O1AAFF18 00000000 
QAQDOO0O ADOOOZ7B 
Q040C0000 8OFFZ3DE 
00000000 H0GD0O0O 
00000000 00000000 
0O0CO00O OO000000 


00000000 80000000 90000000 00000000 
00000000 OOFFO1AON QN000000 00000000 


Figure 3-13. Sample of a Formatted, or Low-Speed, Dump 
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| //PRINTLO JOB MSGLEVEL=(1,1) 


//LIST EXEC PGM=IEBPTPCH 
//SYSPRINT DD SYSOUT=A 
//SYSUT1 DD UNIT=tape, VOL=SER=DUMPTP, LABEL=( NL) , 
// DISP=SHR,DCB=(BLKSIZE=121,RECFM=FBS) 
| //SYSUT2 DD SYSOUT=A 
//SYSIN DD * 


PRINT PREFORM=A 


| /* 


Figure 3-14. Sample JCL Used to Invoke IEBPTPCH to Print Formatted SADMP Output 


//PRINTAPE JOB MSGLEVEL=(1,1) 
//LIST1 EXEC PGM=IEBPTPCH 
ha 
//* PRINT THE FIRST 10 RECORDS 
he | 
//SYSUT1 DD DSN=SADMP. OUTPUT, VOL=SER=DUMPTP, LABEL=(,NL) , 
// —DCB=(RECFM=FBS , LRECL=4160, BLKSIZE=29120) ,UNIT=tape,DISP=SHR 
//SYSUT2 DD SYSOUT=A 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
PRINT STOPAFT=10, TOTCONV=XE 
j* 
//LIST2 EXEC PGM=IEBPTPCH 
| Jf 
//*PRINT THE HEADERS FOR ALL BUT THE FIRST 10 RECORDS 
; : | 
//SYSUT1 DD DSN=SADMP. OUTPUT, VOL=SER=TAPENO, LABEL=(,NL) , 
//  DCB=(RECFM=FBS , LRECL=4160,BLKSIZE=29120) ,UNIT=tape,DISP=SHR 
//SYSUT2 DD SYSOUT=A 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
PRINT MAXFLDS=9, STRTAFT=10 
RECORD FIELD=(8,1,XE,1) 


/* 


Figure 3-15. Sample JCL Used to Invoke IEBPTPCH to Display Portions of a SADMP 
Output Tape | 


//SADCOPY JOB MSGLEVEL=(1,1) 

//COPY EXEC PGM=IEBGENER 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD DUMMY 

//SYSUT1 DD DSN=SADUMP.TAPE,UNIT=tape, 

q] VOL=SER=SADOUT , LABEL=(,NL) ,DISP=SHR, 

// DCB=(RECFM=FBS , LRECL=4160, BLKSIZE=29120, DEN=4) 
//* DEN=3 IS FOR 1600 BPI;DEN=4 IS FOR 6250 BPI 

//SYSUT2 DD  DSN=SADUMP.COPY,UNIT=dasd, 


// VOL=SER=SADCPY ,DISP=(NEW,CATLG) , 
re DCB=(RECFM=FBS , LRECL=4160,BLKSIZE=29120) , 
// SPACE=(4104, (8000, 4000) , LSE) 


Figure 3-16. Sample JCL Used to invoke IEBGENER to Copy SADMP Output Tape to DASD 


SADMP Examples 


The following examples show how to code the AMDSADMP macro instruction to 
create various kinds of stand-alone dump programs. 


Example 1: Accepting All Defaults 


This example shows the AMDSADMP macro instruction coded with no parameters 
to generate an unformatted, direct access resident dump program. 


DUMP1 AMDSADMP 


This is equivalent to coding the following parameters: 


TYPE=UNFORMATTED 
TPL=DSYSDA 
VOLSER=SADUMP 
ULABEL=NOPURGE 
CONSOLE=(01F ,3278) 
SYSUT=SYSDA 
OUTPUT=T282 
LOADPT=X'1000' 
MSG=ALL 

MINAS ID=ALL 
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Example 2: Generating an Unformatted, Tape Resident Dump Program 


In this example, the IPL= parameter specifies tape as the residence volume, and 
the VOLSER= parameter identifies that tape. All other parameters are allowed to 
default. 


AMDSADMP IPL=T3400-2, VOLSER=SATAPE 


i 
1 
rr 
| 


The implied defaults are: 


TYPE=UNFORMATTED 
CONSOLE=(01F , 3278) 
SYSUT=SYSDA 
OUTPUT=T282 
LOADPT=X ‘1000 ' 
MSG=ALL 

MINAS ID=ALL 


Example 3: Generating a Formatted Dump Program with Defaults 


In this example the TYPE= parameter specifies a formatted dump. All other 
parameters are allowed to default. 


AMDSADMP TYPE=LO 


The implied defaults are: 


IPL=DSYSDA 
OUTPUT=PO0E 
VOLSER=SADUMP 
CONSOLE=(01F ,3278) 
ULABEL=NOPURGE 
SYSUT=SYSDA 
ADDR=REAL 
LOADPT=X'1000' 


Example 4: Generating a Formatted Dump Program with Output Directed to 


Tape 
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In this example, the TYPE= and OUTPUT= parameters specify a formatted dump 
directed to tape. All other parameters are allowed to default. 


DUMP2 AMDSADMP TYPE=LO,QUTPUT=T571 


i 
we 
1 


The implied defaults are: 


IPL=DSYSDA 
VOLSER=SADUMP 
CONSOLE=(01F , 3278) 
ULABEL=NOPURGE 
SYSUT=SYSDA 
ADDR=REAL 
LOADPT=X' 1000 ' 
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Introduction 


SPZAP is a service aid program that operates as a problem program. Its purpose is 
to allow you to dynamically update and maintain programs and data sets. With 
SPZAP, an authorized user can: 


Inspect and modify instructions and data in any load module that is a member of 
a partitioned data set 


Inspect and modify data in a specific record in a direct access data set 


Dump an entire data set, a specific member of a partitioned data set, or any 
portion of a data set residing on a direct access device 


Update the system status index (SSI) in the directory entry for any load module. 


SPZAP cannot inspect, modify, or dump data in partitioned data sets extended 
(PDSEs); PDSEs have a data structure that is different from that of partitioned data 
sets (PDSs). For more information about PDSEs and their data structure, refer to 
Managing Non-VSAM Data Sets. 


Capabilities of SPZAP 


The functions of SPZAP provide many capabilities. Three of these are described 
below: 


Using the inspect and modify functions of SPZAP, you can fix programming 
errors that require only the replacement of instructions in a load module without 
recompiling the program. 


Using the modify function of SPZAP, you can set traps in a program by inserting 
invalid instructions. The invalid instructions will force abnormal termination; 
the dump of storage provided as a result of the abnormal termination is a 
valuable diagnostic tool, because it shows the contents of storage at a 
predictable point during execution. 


Using SPZAP to replace data directly on a direct access device, you can 
reconstruct VTOCs or data records that may have been destroyed as the result 
of an 1/O error or a programming error. 


Monitoring the Use of SPZAP 


SPZAP allows its user to modify data on a direct access storage device. Misuse of 
this program could result in serious damage to both user and system load modules 
or data sets. To protect against such damage by SPZAP, an installation controis the 
use of SPZAP. SPZAP is subject to an installation’s security protection scheme, 
except possibly for the VTOC. For the VTOC, the console operator must respond to 
message AMA117D before a job can update a VTOC. 


One means of protecting against unauthorized use of SPZAP is to store SPZAP ina 
security protected private library. Only authorized users of that library would be 
able to execute that private version of SPZAP. Note however, that the private 
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version of SPZAP must be linkedited into the authorized library with an 
authorization code equal to one (AC = 1) if the private version will ever be used to 
update a VTOC, or to zap a VSAM data set or catalog. 


Inspecting and Modifying Data 


SPZAP can be used to inspect and modify data in either a specific record of a direct 
access data set or a load module that is part of a partitioned data set. 


The SPZAP modification function is controlled by the REP (replace) control 
statement. The REP control control statement allows you to replace instructions or 
data at a specific location in a load module or physical record. 


The inspection function is controlled by the VERIFY statement. VERIFY allows you — 
to check the contents of a specific location in a load module or physical record prior 
to replacing it. If the contents at the specified location do not agree with the 
contents as specified in the VERIFY statement, subsequent REP operations are not 
performed. 


To avoid possible errors in replacing data, you should always precede any REP 
operation with a VERIFY operation. 


Inspecting and Modifying a Load Module 


To inspect or modify data in a load module, you need a NAME control statement to 
supply SPZAP with the member name of the load module. The load module must be 
a member of the partitioned data set identified by the SYSLIB DD statement included 
in the execution JCL. 


If the load module being inspected or modified contains more than one control 
section (CSECT), you must also supply SPZAP with the name of the CSECT that is to 
be inspected or modified. If no CSECT name is given in the NAME statement, 
SPZAP assumes that the control section to be pioveeens is the first one 
encountered in searching the load module. 


Whenever SPZAP replaces a CSECT in a load module in response to your REP and 
NAME control statements, it also puts descriptive maintenance data in a CSECT 
identification record (IDR) associated with the load module. This function will be 
performed automatically after all REP statements associated with the NAME 
statement have been processed; any optional user data that has to be placed in the 
IDR will come from the IDRDATA statement. See “SPZAP Control Statements” on 
page 4-11 for an explanation of the IDRDATA statement. 


Accessing a Load Module 
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Once the CSECT has been found, SPZAP must locate the data that is to be verified 
and replaced. This is accomplished through the use of offset parameters in the 
VERIFY and REP statements. These parameters are specified in hexadecimal 
notation, and define the displacement of the data relative to the beginning of the 
CSECT. For example, if a hexadecimal offset of X'40' is specified in a VERIFY 
statement, SPZAP will find the location that is 64 bytes beyond the beginning of the 
CSECT identified by the NAME statement, and begin verifying the data from that 
point. 


Normally, the assembly listing address associated with the instruction to be 
inspected or modified can be used as the offset value in the VERIFY or REP 
statement. However, if a CSECT has been assembled with other CSECTs so that its 
origin is not at assembly location zero, then the locations in the assembly listing do 
not reflect the correct displacements of data in the CSECT. The proper 
displacements must be computed by subtracting the assembly listing address 
delimiting the start of the CSECT from the assembly listing address of the data to be 
referenced. 


To eliminate the need for such calculations and allow you to use the assembly 
listing locations, SPZAP provides a means of adjusting the offset values on VERIFY 
and REP statements. This is achieved through the use of the BASE control 
statement. This statement should be included in the input to SPZAP immediately 
following the NAME statement that identifies the CSECT. The parameter in the 
BASE statement must be the assembly listing address (in hexadecimal) at which the 
CSECT begins. SPZAP then subtracts this value from the offset specified on any 
VERIFY or REP statement that follows the BASE statement, and uses the difference 
as the displacement of the data. 


For a complete description of the control statements mentioned in this discussion, 
see the topic “SPZAP Control Statements” on page 4-11. 


Figure 4-1 on page 4-4 is asample assembly listing showing more than one control 
section. To refer to the second CSECT (IEFCVOL2), you could include in the input to 
SPZAP a BASE statement with a location of 0398. Then, to refer to the subsequent 
LOAD instruction (LR2,CTJCTAD), you could use an offset of 039A in the VERIFY or 
REP statements that follow in the SPZAP input stream. 
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LISTING TITLE 


LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT 


000000 | 1 ITEFCVOL1 CSECT 10000017 
000384 00000000 378 VCNQMSSS DC V(IEFQMSSS) 55800017 

3/9 * 56000017 
000388 00000000 380 VCMSG15 DC V(IEFVMG15) 56100017 
00038C D200 1001 8000 00000 00000 381 MVCMSG MVC 0(1,R1),0(R8) 56200017 

382 * — 56300017 
000392 D200 1001 1000 00001 00000 383 MVCBLNKS MVC 1(1,R1),0(R1) 56400017 

384 * 56500017 
000398 386 CSECT 56600017 
000398 0590 | 387 BALR R9.0 56700017 
00039A | 388 USING *.R9 56800017 
Q0039A 5820 CQ10 © — 90010 389 L R2,LCTJCTAD 56900017 


Figure 4-1. Sample Assembly Listing Showing Multiple Control Sections 


Inspecting and Modifying a Data Record 


To inspect or modify a specific data record, you must use a CCHHR control 
statement to specify its direct access address. This CCHHR address must be within 
the limits of the direct access data set defined in the SYSLIB DD control statement. 


If you request a REP operation for a record identified by a CCHHR control statement, 
SPZAP issues message AMA112I to provide a record of your request. 


Accessing a Data Record 


When you use the CCHHR control statement, SPZAP reads directly the physical 
record you want to inspect or modify. The offset parameters specified in 
subsequent VERIFY and REP statements are then used to locate the data that is to 
be verified or replaced within the record. These hexadecimal offsets must define 
the displacement of data relative to the beginning of the record and include the 
length of any key field. | | 
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Dumping Data 


SPZAP’s dumping options provide a visual representation of the load module or 
data record that has been changed, thus allowing you to double check the 
modifications you have made. 


You use the DUMP and ABSDUMP control statements to specify the SPZAP dumping 
options. The operation codes in the DUMP and ABSDUMP statements indicate the 
kind of dump you want: a formatted hexadecimal dump or a translated dump. The 
parameters identify the portion of the data to be dumped. See “SPZAP Control 
Statements” on page 4-11 for additional information on the DUMP and ABSDUMP 
control statements. 


Updating System Status Information 


The system status index (SSI) is a 4-byte field created by the linkage editor in the 
directory entry of a load module. It is useful for keeping track of any modifications 
that are performed on a load module. SPZAP updates the system status index 
automatically whenever it replaces data in the associated module. 


SPZAP also supplies the SETSSI control statement, that you can use to overlay the 
existing data in the SSI with your own data. For a complete description of the 
SETSSI control statement, see “SPZAP Control Statements” on page 4-11. 


Not all load modules have system status information. In those that do, the SSI 
system status index is located in the last four bytes of the user data field in the 
directory entry. Figure 4-2 shows the position of the SSI in load module directory 
entries. 


Figure 4-2. SSI Bytes in a Load Module Directory Entry 


Member Name C User Data Field SSI 
1 8 11 12 13 to 70 maximum variable 


Figure 4-3 on page 4-6 shows the composition of the SSI field and the flag bits used 
to indicate the types of changes made to the corresponding load module program. 


The first byte of SSI information contains the member’s change level. When a load 
module is initially released by IBM, its change level is set at one. Thereafter, the 
change level is increased by one for each release that includes a new version of 
that program. If you make a change to the SSI for any of the IBM-released 
programs, take care not to destroy this maintenance level indicator unless you 
purposely mean to do so. To keep the change level byte at its original value, find 
out what information is contained in the SSI before using the SETSSI function. The 
LISTLOAD control statement of the LIST service aid can give you the information 
you need. 
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1 byte | byte 2 bytes 


Change Flag Serial 
Level | Byte Number 


(Réserved) “ere 
ROrce Lager sess ase 
Local ix Flag 
Program Temporary Fix Flag~ 
Dependency Flag ------ nnn 
Critical Flag ---------~----~-----------------------! 
IBM Flag ------------------------------------------------ 


Figure 4-3. Flag Bytes in the System Status Index Field | 


The second byte of the SSI is termed the flag byte. Bits within the flag byte contain 
information reflecting the member’s maintenance status. You need only be 
concerned with two of the eight bits when you are using SPZAP: 


e Bit 2, the local fix flag, indicates that the user has modified a particular member. 
(It is not used to reflect modifications made by IBM-supplied program temporary 
fix ora PTF.) SPZAP sets this local fix flag bit to one after successfully 
modifying a load module. 3 


¢ Bit 3, the program temporary fix flag, is set to one when an IBM-authorized PTF 
is applied to a system library to correct an error in an IBM module. 


All other bits in the flag byte should be retained in the SSI as they appeared before 
the SETSSI operation took place, so as not to interfere with the normal system 
maintenance procedures. 


The third and fourth bytes of the system status index are used to store a serial 
number that identifies the first digit and the last three digits of a PTF number. 
SPZAP will not change these bytes unless you request a change by using the 
SETSSI control statement. 


Operational Considerations 
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Consider the following points when you run SPZAP: 


¢ SPZAP cannot inspect, modify, or dump data in partitioned data sets extended 
(PDSEs); PDSEs have a data structure that is different from that of partitioned 
data sets (PDSs). For more information about PDSEs and their data structure, 
refer to Managing Non-VSAM Data Sets. 


¢ SPZAP uses the system OPEN macro. Therefore, SPZAP cannot modify or 
inspect security protected data sets when SPZAP cannot successfully complete 
the authorization checks that occur during the OPEN. 


e Unexpired data sets such as system libraries cannot be modified unless the 
operator replies r xx,‘U’ to the expiration message that occurs during OPEN. 


e If SPZAP is used to modify an operating system module that is made resident in 
virtual storage only at IPL time, an additional IPL is required to invoke the new 
version of the altered module. (Note that this includes all modules in 
SYS1.LPALIB.) 


¢ The SYSLIB DD statement cannot define a concatenated or a multi-volume data 
set. | 


¢ SPZAP supports only direct access devices for the SYSLIB device. 
e SPZAP is a non-reusable module. 


e When modifying a system data set, such as SYS1.LINKLIB, specify DISP = OLD 
on the SYSLIB DD statement. 


JCL Statements 


SPZAP is executed using the following job control statements. The minimum region 
size needed is 17K plus the larger of 3K or the blocksize in bytes for the data set 
specified on the SYSLIB DD statement. 


JOB Statement 
marks the beginning of the job. 


EXEC Statement 
invokes AMASPZAP using either PGM=AMASPZAP or PGM=IMASPZAP. The 
only valid parameter that you may specify is PARM=IGNIDRFULL, which 
enables SPZAP to override the standard restrictions placed upon CSECT 
updates (via NAME and REP) when IDR space for the module is found to be full. 


Note: Use PARM=IGNIDRFULL with caution. It should be avoided for 
IBM-maintained modules. 


SYSPRINT DD Statement 
defines a sequential output message data set, that can be written on a system 
printer, a magnetic tape volume, or a direct access volume. This statement is 
required for each execution of SPZAP. 


SYSLIB DD Statement 
defines the direct access data set that will be accessed by SPZAP when 
performing the operations specified on the control statements. The DSNAME 
parameter and DISP= OLD or DISP=SHR are required. The VOLUME and UNIT 
parameters are necessary only if the data set is not cataloged. When this data 
set is the VTOC, you must specify DSNAME = FORMAT4.DSCB. This statement 
cannot define a concatenated or multi-volume data set. It is required for the 
execution of SPZAP. 
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Return Codes 
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Notes: 


1. When you access a record in the VTOC (that is, a DSCB) for modification, | 
SPZAP issues message AMA117D to the console. No message is issued, 
however, when an ABSDUMPT operation is performed on the VTOC. 


2. When you access a VSAM object (for example, rebuilding a catalogue), you 
are required to reference the appropriate catalogue. If you fail to include a 
STEPCAT or JOBCAT card referring to the appropriate user catalogue, your 
job might fail. If it does, your job is assigned an abend 913-C; the data set is 
dumped; and, the system displays message IEC150I. 


SYSABEND DD Statement 
defines a sequential output data set to be used in case SPZAP terminates 
abnormally. The data set can be written to a printer, a magnetic tape volume, 
or a direct access volume. This statement is optional. 


SYSIN DD Statement 
defines the input stream data set that contains SPZAP control statements. 


When SPZAP terminates, it issues one of the following return codes: 


Code Meaning 


0 Successful completion. 

4 Warning of a condition that may result in future errors if remedial action 
is not taken. 

8 A SPZAP input statement contains an error or was overridden by © 


operator intervention. 


12 A requested JCL statement is absent or specifies a data set that was not 
successfully opened. SPZAP terminates immediately. 


16 A permanent I/O error has occurred, perhaps caused by a JCL error, 


such as invalid blocksize. SPZAP terminates immediately. 


20 | A record is larger than the blocksize. SPZAP terminates immediately. 


Dynamic Invocation of SPZAP 


SPZAP can be invoked by an application program at execution time through the use 
of the CALL, LINK, XCTL, or ATTACH macro instruction. The program must supply a 
list of alternate ddnames of data sets to be used by SPZAP if the standard ddnames 
are not used. 


The general form of these macros when used to invoke SPZAP is shown below. 


(anyname) CALL AMASPZAP, (oplistad,ddnamadr) ,VL 
(anyname) XCTL EP=AMASPZAP 
(anyname) LINK EP=AMASPZAP,PARAM=(oplistad,ddnamadr) ,VL=1 


| (anyname) ATTACH EP=AMASPZAP,PARAM=(oplistad,ddnamadr) ,VL=1 | 


anyname 
indicates an optional statement label on the macro statement. 


EP is the entry point - in each case for the SPZAP program. 


PARAM 
specifies, as a sublist, address parameters to be passed from the program to 
SPZAP. 


oplistad 
specifies the address, if present, of either a halfword of zeros (indicating no 
options) or a non-zero halfword followed by a character string whose length is 
given in halfwords. For possible parameter values, see “JCL Statements” in 
this chapter. 


ddnamadr 
specifies the address of a variable-length list containing alternate ddnames for : 
data sets to be used during SPZAP processing. If all the standard ddnames 
(SYSPRINT, SYSLIB, and SYSIN) are used, then this parameter can be omitted. 


The ddname list must begin on a halfword boundary. The first two bytes contain 
a count of the number of bytes in the rest of the list. The format of the list is 
fixed, with each entry having eight bytes. Any name of less than eight bytes 
must be left justified and padded with blanks. If a name is left out in the list, the 
entry must contain binary zeros; the standard name is then assumed. Names 
can be omitted from the end of the ddname list by shortening the list. 


The sequence of 8-byte entries in the list is as follows: 


Entry Standard name 
0-7 not applicable 
8-15 not applicable 
16-23 not applicable 
24-31 SYSLIB 

32-39 SYSIN 

4-47 SYSPRINT 
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ven 


indicates that the sign bit is to be set to 1 in the last word of the address 
parameter list. 


Figure 4-4 is an example of two functionally equivalent dynamic invocations of 


SPZAP. 


EXSPZAP CSECT 
USING *,15 
MODID 
SAVE (14,12) 
BALR 12,0 
USING *,12 
ST 13, SAVEAREA+4 
LR 2513 
LA 13 ,SAVEAREA 
ST 13,8(0,2) 


ASSUME REG15 IS BASE 

MODULE ID AND DATE IN PROLOG 
SAVE REGISTERS 

ESTABLISH BASE REGISTER 


CHAIN NEW SAVEAREA TO PREVIOUS 
TEMPORARILY SAVE ADDRESS OF OLD SAVEAREA 
INIT REG13 WITH ADDRESS OF NEW SAVEAREA 
CHAIN PREVIOUS SAVEAREA TO NEW 


KEREKKEKREREKRRERKRKEERERERERRRRERREERKRRERERRERRRRERREREREERKRERERERERERERERRERERE 


INVOCATIONS OF SUPERZAP. 


THIS EXAMPLE SHOWS TWO FUNCTIONALLY EQUIVALENT DYNAMIC 


NO OPTIONS ARE PASSED. 


4 FF FF HF H 


THE DDNAME FOR THE SYSLIB FILE IS CHANGED TO TESTLIBR. 
THE DDNAME FOR THE SYSIN FILE IS NOT CHANGED. 
THE DDNAME FOR THE SYSPRINT FILE IS CHANGED TO PRINTOUT. 


+ + FF F FF SF HF 


KKEKREKREKRKREERKRRRREREKRRERERERREKRERRERERRRRERERERERRREERERRREEEKRERREERERREREREREREEEE 


LINKZAP1 LINK EP=AMASPZAP,PARAM=(OPTLIST,DDLIST) ,VL=1 
LINKZAP2 LINK EP=AMASPZAP,PARAM=(0,DDLIST) ,VL=1 


L 


13,SAVEAREA+4 LOAD ADDRESS OF PREVIOUS SAVEAREA 


RETURN (14,12),T,RC=0 RETURN TO CALLER 


OPTLIST DC 
| DDLIST DS 
: DC 

* 

DC 
DC 
DC 


DC 


* 


SAVEAREA DC 


END 


H'@Q' NO OPTIONS ARE PASSED TQ AMASPZAP 

OH ALIGN DDNAMES TO HALFWORD BOUNDARY 

H'48' LENGTH OF THE CHARACTER STRING 
CONTAINING DDNAME OVERRIDES 

24XL1'00' FIRST 24 CHARACTERS ARE IGNORED 

CL8'TESTLIBR' CHANGE SYSLIB FILE TO DDNAME OF TESTLIBR 

8XL1'00' USE SYSIN FILE FOR INPUT OF CONTROL 
STATEMENTS 

CL8'PRINTOUT' CHANGE SYSPRINT FILE TO DDNAME OF 
PRINTOUT 

18F'O' REGISTER SAVEAREA 


Figure 4-4. Sample Assembler Code for Dynamic Invocation of SPZAP 
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SPZAP Control Statements 


SPZAP control statements (entered either through the user’s input stream or 
through the system console) define the processing functions to be performed during 
a particular execution of SPZAP. 


Coding Rules for SPZAP Control Statements 


They can begin in any column, but the operation name must precede the 
parameters. 


There must be at least one blank between the specified operation name and the 
first parameter. 


All parameters must also be separated by at least one blank space. 


Data field parameters may be formatted with commas for easier visual check, 
but embedded blanks within data fields are not permitted. 


Data and offset values must be specified as a multiple of two hexadecimal 
digits. 


The size of an SPZAP control statement is 80 bytes. 


Following the last required parameter and its blank delimiter, the rest of the 
space on most control statements can be used for comments. Exceptions to this 
are the NAME and DUMP control statements: if the CSECT parameter is omitted 
from either of these statements, the space following the load module parameter 
should not be used for comments. 


A record beginning with an asterisk and a blank is considered to be a comment 
statement. 


Following are detailed descriptions of the SPZAP control statements, in the order in 
which you usually code them. 


NAME member [csect | 


identifies a CSECT in a load module that is to be the object of subsequent 
VERIFY, REP, or SETSSI operations. The variables are: 


member 
the member name of the load module that contains the control section in 
which the data to be inspected or modified is resident. The load module 
must be a member of the partitioned data set defined by the SYSLIB DD 
statement. 


csect 
the name of the particular control section that contains the data to be 
verified or replaced. If this variable is omitted, it is assumed that the first 
CSECT contained in the load module is the one to be used. If there is only 
one CSECT in the load module, this variable is not necessary. 


Note: You can define more than one NAME statement in your input to SPZAP. 
However, the VERIFY, REP and SETSSI statements associated with each NAME 
statement must immediately follow the NAME statement to which they apply. 


Chapter 4. SPZAP 4-11 


4-12 Service Aids 


CCHHR record address 
identifies a physical record on a direct access device that is to be modified or 
verified. The record must be in the data set defined by the SYSLIB DD 
statement. Any immediately following REP or VERIFY statements will reference 
the data in the specified record. The variable is: . 


record address : 


the actual direct access address of the record containing data to be 
replaced or verified. It must be specified as a 10-digit hexadecimal number 
in the form cccchhhhrr, where cccc is the cylinder, hhhh is the track, and rr 
is the record number. For example, 0001000A01 addresses record 1 of | 
cylinder 1, track 10. A zero record number is invalid and defaults to 1. 


Note: You can define more than one CCHHR statement in your input to SPZAP. 
However, the VERIFY, REP and SETSSI statements associated with each CCHHR 
statement must immediately follow the specific CCHHR statement to which they 
apply. 

{VERIFY|VER}! offset expected-content | 
causes the data at a specified location within a CSECT or physical record to be 
compared with the data supplied in the statement. 


offset 


is the hexadecimal displacement of data to be inspected in a CSECT or 
record. This displacement does not have to be aligned on a fullword 
boundary, but it must be specified as a multiple of two hexadecimal digits 
(OD, 021C, 014682, etc.). If this offset value is outside the limits of the 
CSECT or data record defined by the preceding NAME or CCHHR statement, 
the VERIFY statement will be rejected. When inspecting a record with a key, 
the length of the key should be considered in the calculation of the 
displacement; that is, offset zero is the first byte of the key. 


expected-content 


defines the bytes of data that are expected at the specified location. As with 
the offset variable, the number of bytes of data defined must be specified as 
a multiple of two hexadecimal digits. If desired, the data within the 
parameter may be separated by commas (never blanks), but again, the 
number of digits between commas must also be a multiple of two. For 
example, expected content might look like this: 


5840C032 (without commas), 
or like this: 
5840,C032 (with commas) 


If all the data does not fit into one VERIFY statement (80-byte logical record), 
then another VERIFY statement must be defined. 


Note: If the two fields being compared are not in agreement, that is, if the 
VERIFY operation is rejected, no succeeding REP or SETSSI operations are 
performed until the next NAME or CCHHR control statement is encountered. 
SPZAP provides a formatted dump of each CSECT or record for whicha 
VERIFY operation failed. 


REP offset data 
modifies data at a specified location in a CSECT or physical record that was 
previously defined by a NAME or CCHHR statement. The data specified on the 
REP statement will replace the data at the record or CSECT location stipulated 
in the offset variable field. (Always use the VERIFY function to make sure you 
know what you are going to change with the REP function.) SPZAP issues 
message AMA122I to record the contents of the specified location as they were 
before the change was made. 


offset 


provides the hexadecimal displacement of data to be replaced in a CSECT 
or data record. This displacement need not address a fullword boundary, 
but it must be specified as a multiple of two hexadecimal digits (OD, 02C8, 
001C52). If the offset value is outside the limits of data record (physical 
block) or CSECT being modified, the replacement operation will not be 
performed. When replacing data in a record with a key, the length of the 
key should be considered in the calculation of the displacement; that is, 
offset zero is the first byte of the key, not of the data. 


data 


defines the bytes of data to be inserted at the location. As with the offset 
variable, the number of bytes of data defined must be specified as a 
multiple of two hexadecimal digits. If desired, the data within the variable 
may be separated by commas (never blanks); but again, the number of 


_ digits between commas must also be a multiple of two. For example, a REP 


data variable may look like this: 


4160B820 (without commas) 
or like this: 
4160,B820 (with commas). 


If all the data to be modified does not fit into one REP statement (an 80-byte 
logical record), you can code another REP statement. 


Notes: 


Remember that SPZAP automatically updates the system status index (SSI) 
when it successfully modifies the associated load module. For more 
detailed information about SSI, see “Updating System Status Information” in 
this chapter. 


If you are performing multiple VERIFY and REP operations on a CSECT, 
make sure that all the VERIFY statements precede all the REP statements. 
This procedure ensures that all REP operations are ignored if one VERIFY 
reject occurs. 


When you access a record in the VTOC (that is, the DSCB) for modification, 
SPZAP issues the message AMA117D to the console. No message is 
issued, however, when an ABSDUMPT operation is performed on the VTOC. 
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IDRDATA xXxxxxxxx 


causes SPZAP to place up to eight bytes of user data into the SPZAP CSECT 
identification record of the load module; this is only done if a REP operation 
associated with a NAME statement is performed and the load module was 
processed by the linkage editor to include CSECT identification records. The 
variable is: 


XXXXXXXX 
eight (or fewer) bytes of user data (with no embedded blanks) that are to be 
placed in the user data field of the SPZAP IDR of the named load module. If 
more than eight characters are in the variable field, a the first eight 
characters will be used. 


Note: The IDRDATA statement is valid only when used in conjunction with the 
NAME statement. It must follow its associated NAME statement and precede 
any DUMP or ABSDUMP statement. IDRDATA statements associated with 
CCHHR statements will be ignored. 


SETSSI xxyynnnn 


places user-supplied system status information in the PDS directory entry for 
the library member specified in the preceding NAME statement. The SSI, 
however, must have been created when the load module was link edited. The 
variable is: 


xxyynnnn 
four bytes of system status information the user wishes to place in the SSI 
field for this member. Each byte is supplied as two hexadecimal digits 
indicating the following: 


XX - change level 
yy - flag byte 
nnnn - modification serial number 


lf SPZAP detects an error in any previous VERIFY or REP operation, the SETSS! 
function is not performed. 


Note: Because all bits in the SSI entry are set (reset) by the SETSSI statement, 
be very careful when using it to avoid altering the vital maintenance-status 
information. SPZAP issues message AMA122I to record the SSI as it was before 
the SETSSI operation was performed. (See “Updating System Status 
Information” on page 4-5.) 


{DUMP|DUMPT} member {csect|ALL} 


dumps a specific control section or all control sections in a load module. The 
output format of this dump is hexadecimal. See the topic “SPZAP Output” on 
page 4-18 for further information. The DUMPT statement differs from the DUMP 
statement in that it also produces an EBCDIC and an instruction mnemonic 
translation of the hexadecimal data. The variables are: 


member | 
the member name of the load module that contains the control section(s) to 
be dumped. (Note: This load module must be a member of a partitioned 
data set that is defined by the SYSLIB DD statement.) 


csect 
defines the name of the particular control section that is to be dumped. To 
dump all the CSECTs of a load module, code “ALL” instead of the CSECT 
name; if the CSECT variable is omitted entirely, SPZAP assumes that you 
mean to dump only the first control section contained in the load module. 


Note: DUMP or DUMPT applied to a CSECT consisting only of space allocations 
(DS statements) will produce no output between the statement printback and the 
dump-completed message. 


{ABSDUMP|ABSDUMPT} {startaddr stopaddr|membername]|ALL} 
used to dump a group of data records, a member of a partitioned data set, or an 
entire data set, as defined in the SYSLIB DD statement. If the key associated 
with each record is to be formatted, DCB = (KEYLEN=nn), where “nn” is the 
length of the record key, must also be specified by the SYSLIB DD statement. 
Note that when dumping a VIOC, DCB = (KEYLEN = 44) should be specified; 
when dumping a PDS directory, DCB = (KEYLEN = 8) should be specified. 
ABSDUMP produces a hexadecimal printout only, while ABSDUMPT prints the 
hexadecimal data, the EBCDIC translation, and the mnemonic equivalent of the 
data (see “SPZAP Output” on page 4-18). The variables are: 


startaddr 
is the absolute direct access device address of the first record to be 
dumped. This address must be specified in hexadecimal in the form 
ceccchhhhrr (cylinder, track and record numbers). 


stopaddr 
is the absolute direct access device address of the last record to be 
dumped, and it must be in the same format as the start address. 


Note: Both addresses must be specified when this method of dumping 
records is used, and both addresses must be within the limits of the data set 
defined by the SYSLIB DD statement. The record number specified in the 
start address must be a valid record number. If a record number of 0 is 
specified, SPZAP will change it to 1 since the READ routine skips over such 
records. The record number specified as the stop address need not be a 

~ valid record number, but if it is not, the dump will continue until the last 
record on the track specified in the stop address has been dumped. 


membername 
is the name of a member of a partitioned data set. The member can bea 
group of data records or a load module. In either case, the entire member 
is dumped when this variable is specified. 


ALL 
specifies that the entire data set defined by the SYSLIB DD statement is to 


be dumped. How much of the space allocated to the data set is dumped 
depends on how the data set is organized: 


¢ For sequential data set, SPZAP dumps until it reaches end of file. 


e For indexed sequential and direct access data sets, SPZAP dumps all 
extents. 


e For partitioned data sets, SPZAP dumps all extents, including all linkage 
editor control records, if any exist. 
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BASE xxxxxx 


used by SPZAP to adjust offset values that are to be specified in any subsequent 
VERIFY and REP statements. This statement should be used when the offsets 
given in the VERIFY and REP statements for a CSECT are to be obtained from 
an assembly listing in which the starting address of the CSECT is not location 
zero. | 


For example, assume that CSECT ABC begins at assembly listing location 
X'000400', and that the data to be replaced in this CSECT is at location 


- X'000408'. The actual displacement of the data in the CSECT is X'08'. 


However, an offset of X'0408' (obtained from the assembly listing location 
X'000408') can be specified in the REP statement if a BASE statement 
specifying X'000400' is included prior to the REP statement in the SPZAP input 
stream. When SPZAP processes the REP statement, the base value X'000400' 


will be subtracted from the offset X'0408' to determine the proper displacement 


of data within the CSECT. The variable is: 


XXXXXX : 
is a 6-character hexadecimal offset that is to be used as a base for 
subsequent VERIFY and REP operations. This value should reflect the 
starting assembly listing address of the CSECT being inspected or modified. 


Note: The BASE statement should be included in the SPZAP input stream 
immediately following the NAME statement that identifies the control section 
that is to be involved in the SPZAP operations. The specified base value 
remains in effect until all VERIFY, REP, and SETSSI operations for the CSECT 
have been processed. ? 


CONSOLE 


indicates that SPZAP control statements are to be entered through the system 
console. 


When this statement is encountered in the input stream, the following message 
is written to the operator: 


AMA116A ENTER AMASPZAP CONTROL STATEMENT OR END 


The operator may then enter in any valid SPZAP control statement conforming 
to the specifications described in the beginning of this control statement 
discussion. After each operator entry through the console is read, validated, 
and processed, the message is reissued, and additional input is accepted from 
the console until “END” is replied. SPZAP will then continue processing control 
statements from the input stream until an end-of-file condition is detected. 


Note: The control statements can be entered through the console in either 
upper or lower case letters. 


* (Comment) | 


used to annotate the SPZAP input stream and output listing. Any number of 
comment statements can be included in the input stream. When such a 
statement is encountered, SPZAP writes the entire statement to the data set 
specified for SYSPRINT. | 


Note: The asterisk (*) can be specified in any position of the statement, but it 
must be followed by at least one blank space as a delimiter. 


CHECKSUM [hhhhhhhh ] 
used to print or verify a fullword checksum (parity-check). All of the valid 
hexadecimal operands since the preceding CHECKSUM statement or SPZAP 
initialization are logically concatenated into a single string divided into 
fullwords, the sum of which is the checksum. For example, the string 
12345678FACE produces the checksum 0D025678. Each CHECKSUM statement 
resets the accumulated checksum value to zeros. 


The CHECKSUM statement is effective in detecting clerical errors that may 
occur when transcribing an SPZAP type of fix. CHECKSUM does not prevent 
errors; it only causes a message to be issued. By the time the CHECKSUM 
statement is processed, all prior replaces have been done. 


hhhhhhhh 
are 8 hexadecimal characters that are compared with the checksum. If the 
two values are equal, a message is written indicating that the checksum 
was correct and has been reset. 


If the operand field is blank, a message is written giving the actual value of 
the checksum, and indicating that the checksum has been reset. 


When the CHECKSUM control statement is provided with an incorrect 
operand, the REP and SETSSI statements processed already are not 
affected. 


If the operand is invalid or is not equal to the checksum, a message is 
written indicating invalid operand or checksum error. All subsequent REP 
and SETSSI statements are ignored until the next NAME or CCHHR 
statement is encountered. The results of previously processed statements 
are not affected. 
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SPZAP Output 


SPZAP provides two different dump formats for the purpose of checking the data 
that has been verified or replaced. These dumps (written to the SYSPRINT data set 
specified by the user) may be of the formatted hexadecimal type or the translated 
form. Both formats are discussed below in detail with examples showing how each 
type will look. 


Formatted Hexadecimal Dump 


When DUMP or ABSDUMP is the control statement used, the resulting printout is a 
hexadecimal representation of the requested data. Figure 4-5 on page 4-19 givesa 
sample of the formatted hexadecimal dump. A heading line is printed at the 
beginning of each block. This heading consists of the hexadecimal direct access 
address of the block, a two-byte record length field, and the names of the member 
and the control section that contain the data being printed (if the dump is for specific 
CSECT or load module). Each printed line thereafter has a three-byte displacement 
address at the left, followed by eight groups of four data bytes each. The following 
message: 


AMA113I COMPLETED DUMP REQUIREMENTS 


is printed under the last line of the dump printout. 


Translated Dump 


4-18 Service Aids 


The control statements DUMPT and ABSDUMPT also provide an operation code 
translation and an EBCDIC representation of the data contained in the dump. 

Figure 4-6 on page 4-20 shows the format of the translated dump. The first byte of 
each halfword of data is translated into its mnemonic operation code equivalent, 
provided such a translation is possible. If there is not equivalent mnemonic 
representational value to be given, the space is left blank. This translated line of 
codes and blanks is printed directly under the corresponding hexadecimal line. An 
EBCDIC representation of each byte of data is printed on two lines to the right of the 
corresponding line of text, with periods (.) substituted for those bytes that do not 
translate to valid printable characters. 


6k-p dvVZdS ‘pv s9ideyD 


UUMP ITEAMVESN ALL 


* *CCHHR- 
000000 
000020 
000040 
000060 
000080 
0000A0 
0000C0 
0000E0 
000100 
v00120 
J00140 
“00160 
000180 
0001A0 
0001C0 
0001£0 
000200 
000220 
000240 
000260 
000280 


O0O006E0 
000700 


* *CCHitk- 
000000 
000020 
000040 
000060 
000080 
OOO00A0 
0000C0 
QO000E0 
000100 
000120 
000140 


0022001108 


47FOFO14 
D04850D0 
9200C2F4 
9200C2FC 
951858E0 


OAL495FF 


C2084710 
OA1L447F0O 
50210000 
C2FC9200 
10149601 
£0104110 
918CD505 
000C1 5814 
vz2051004 
96FCD201 
47F 09236 
00011932 
00105822 
91023003 
D2U52094 


4ir0C014 
FOOOYEEO 
5809648 
00000708 
96C25881 
1000D24F 


C7FE58H0 — 


4180C001 
00000000 


0022001108 


00000724 
E340D9C5 
C4C1E3C1 
408 3D640 
D640 ES D6 
C1D9C540 
C2CSD340 
C5C 8F3F3 
4OE6D9C9 
CSD3E24B5 
CSE2EzC5 


RECORD LENGTH- 0850 


OECSE2D5 
10045010 
D20EC 2F5 
D203C 320 
96484520 
C3274780 
90F89110 
910A9 180 
92B01 000 
C3009 4F7 
101748L0 
FOOOOAOA 
30041004 
41400001 
301C1B33 
100A9 6FC 
5$810C 224 
47709 22C 
00284832 
47109270 
- 4122 


BLU tae 
D205F 00 
CO80F337 
O7FE1BDD 
04000 668 
00001288 
FOO0B000 
C31C4100 
41F00018 
43A0400B 


RECORD LENGTH- 


0000073F 
C340D6D9 
GOE2C5E3 
ESD6D3E4 
D3E4D4cC5 
DSD6E340 
E3D9C1C3 
F5C940D7 
E3C9D5C7 
&0D5D640 
C44B58B0 


60E6D9C1 
D00818Di1 
C2F49108 
C31 C95FF 
95705820 
910A9108 
C2084710 
C1FC4780 
OA1L495SFF 
A04&29101 
FOOS4CEO 
1B&44340 
W¥7F09192 
D2031000 
403096FC 
5010C224 
95801002 
41220001 
00005930 
41220002 
000C5020 


100801 FF 
F001C080 


7TFFFOO0O 


41800668 
478096D8 
41BB0050 
0280181Bb 
50E09648 


00000750 
KOEYDSD3 
OF4O04040 
D4 C54 DE2 
4DE25D51 
D4 D6 E5SC5S 
D240C1D3 
CS5D9D4c1 
HOEGE2C5 
D4 D6D9CS 


46A113I COMPLETED DUMP REQUIREMENTS 


Figure 4-5. Sample Formatted Hexadecimal Dump 


0850 


D760E4D7 
5810D000 
C20C4710 
C32A4770 
CZ640700 
C20C4710 
90F80700 
9168947F 
C3344780 
C2094780 
F0069101 
C2245810 
D505301C 
301095FF 
DZ01100A 
4240C224 
47709236 
402096FC 
92 B44780 
W7FO09246 
C2009640 


41110002 
0006D201 
96FOF 004 
58F09660 
1BF8189F 
95801008 
50B0C 320 
41110000 
85E09518 


00000761 
C1C2C5 D3 
40404040 
5D1CD5 Dé 
C9CS5C 8F3 
C4 61C3 D6 
D3D6C3C1 
D5CS5 DS E3 
D94LOD6E4 
40D3C1C2 


60606000 
9 200D00C 
9069500 
908A41 80 
45109098 
91685820 
451090D8 
C1FC4TFO 
96DC41A0 
91689102 
10204710 
C2245830 
10044780 
30024780 
96FC41 30 
9110C208 
D20196FC 
D201100A 
9 2881233 
D203Cz28 
C20947F0 


SOF 

GW1lFFOOUS 
58FFO0000 
D503C31C 
4770969A 
1BBB43B0 


OAOAD707. 


58E09648 


MEMBER NAME 


00000775 
C5CH840 3 
4¥O0C4C1E3 
E340D4D6 
F3F1C940 
D7C9ICSCY 
E3C5C4&40 
40C961D6 
E3D7E4UE3 
CSD3E240 


9O0ECDOOC 
92FFD008 
C2FC4780 
c00141F0 
00000000 
C2749581 
00000000 
908A0700 
cC0089200 
C2094710 
915E4100 
C27C4833 
91E84111 
91C0D205 
00019580 
47109204 
100A 48 20 
96FC9140 
47809268 
C2005820 


75 c0Y6EFC 
4¥iFFOOO01 
D219C014 
97004780 
96FFC 334 
C32806B0 
C31¢CC31C 
45209570 


00000793 
C1D7C50F 
C140E2C5 
E5C5C 460 
EXE2CS5D9 
4B4&ODSDE6 
C6D6D940 
4OC5D9D9 
GOE3D9C1 
E6C9D3D3 


189F5010 
9140C20A 
9064D203 
001450E0 
50210000 
20114770 
50210000 
45109100 
C2F49200 
91685810 
EOO084&7FO 
OOOE9ISFF 


000C4KE40. 


10043004 
10024780 
9102C208 
96FC8122 
C2094710 
91203012 
C200D203 

004143 


Lan BU 
4111000 
F0019200 
96D89500 
07FE58B0 
& 2B0C328 
1BFFO7FE 
47F09112 


IEHMVESN CSECT NAME 


000007 E6 
C9CSC8F3 
E312C3D6 
C3D6D7C 9 
40D3C1C2 
4 OEYE2C5 
C9 D5 D7 E& 
D6D940E6 
C9D3CSD9 
80C2C540 


MEMBER NAME IEHMVESN CSECT NAME IEHMVSSN 


DO484110 
&K780908A 
C3009664 
964845E0 
92801000 
90D09102 
92801000 
00000000 
C2F89200 
C27458F0 
91624100 
30024780 
917A8140 
47F091C6 
91E248030 
47109204 
00014130 
92B85820 
4780926§ 


9634926P 
46009604 
C33CO7FE 
C3284780 
C32058F0 
41F00008 
9600C334 
8CA00000 


LEHMVMSN 


19E&DS5C9 
F6F1C940 
D7C9CSC4& 
CSC4&40E3 
CSD3E240 
D940D3C1 
E34B66C9 
C8C9D3C5 
4&0D3C1C2 
D7D9D6C3 


| HMASPZAP INSPECTS, MODIFIES, AND DUMPS CSECTS OR SPECIFIC DATA KECORDS ON DIRECT ACCESS STORAGE. 
DUMPT IEHMVESN ALL 


| **CCHHR- 0022001108 RECORD LENGTH- 0850 MEMBER NAME IEHMVESN CSECT NAME IEHMVSSN 


SPIV 89INOS = Qe-p 


000 2g 


Figure 4-6. Sample Translated Dump 
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000040 9200 C2F& D20E C2F5 C2F4 9108 C20C 4710 90E6 9500 C2FC 4780 9064 D203 C300 9664 *..B4K.B5B4..B...# 
MVI MVC TM BC STM CLI BC ST™ MVC OI Wee Bowe ee Ke Cece 
000060 9200 C2FC D203 C320 C31C 95FF C32A 4770 908A 4180 C001 41FO 0014 SOEO 9648 4SEO *..B.KsC.Cu.cC eas 
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BC . STM TM BC STM BCR BAL STM ST MVI LPR no Pere ren 
OOO0EO O0A14 47FO 910A 9180 CiFC 4780 9168 947F C1FC 47FO0 908A 0700 4510 9100 06000 0000 2 20 secs cee 
Svc BC ™ TM BC T™ «NI BC STM BCR BAL TM WA 6 606 sss See dcs oc 
000100 5021 0000 9280 1000 OA14 95FF C334 4780 96DC 41A0 C008 9200 C2F4& 9200 C2F8 9200 a ee eee oe 
ST MVI LPR svc CLI BC oI LA MV I MVI MV1 #0000 e eB. WBS... 
000120 C2FC 9200 C300 94F7 A042 9101 C209 4780 9168 9102 C209 4710 9168 5810 C274 58FO Bos 2 Cia 7 sace Bens 
MVI ; NI T™ BC TM TM BC TM L L #000 Bocce ee eBe OF ff - 
000140 1014 9601 1017 48EO FOO&S 4SCEO F006 9101 1020 4710 915E 4100 E008 4S7FO 9162 4100 © nesses Osks0in. © 1 
LPR OI #£ULPR LH SRP MH SRP IM LPR BC TM LA BC Ti LA eee eT er ere 
000160 £010 4110 F000 OAOA 1B44 4340 C224 5810 C224 5830 C27C 4833 OO0E 95FF 3002 4780 Pe ccOscces es “Bade 
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000180 918C b505 3004 1008 47F0 9192 D505 301C 1004 4780 91E8 4111 OO00C 4640 917A 4140 2 ws sac 0c Neos 
IM CLC  LPER LPR BC TM . CLC LPER LPR BC TM LA BCT TM LA 926 566V bese. ots 
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SPZAP Examples 


Example 1: Inspecting and Modifying a Load Module Containing a Single 
CSECT 


This example shows how to inspect and modify a load module containing a single 
CSECT. 


//ZAPCSECT JOB MSGLEVEL=(1,1) 
//STEP EXEC PGM=AMASPZAP 
//SYSPRINT DD SYSOUT=A 
//SYSLIB DD DSNAME=SYS1.LINKLIS,DISP=OLD 
//SYSIN DD * 
NAME IEEVLNKT 


VERIFY 0018 — C€9C8,D2D9,D1C2,C7D5 
REP 0018 E5C6,D3D6,E6FO,4040 
SETSSI 01211234 
TDRDATA 71144 

TEEVLNKT 


In this example: 


SYSLIB DD Statement 
defines the system library SYS1.LINKLIB containing the module IEEVLNKT that 
SPZAP is to process. 


SYSIN DD Statement 
defines the input stream. 


NAME Control Statement 
instructs SPZAP that the operations defined by the control statements that follow 
are to be performed on the module IEEVLNK7. 


VERIFY Control Statement 
requests that SPZAP check the hexadecimal cata at offset X'0018' in the 
module IEEVLNKT to make sure that it is the same as the hexadecimal data 
specified in this statement. If the data is the same, SPZAP continues processing 
the subsequent statements sequentially. If the data is not identical, SPZAP will 
not perform the REP and SETSSI operations requested for the module. It will, 
however, perform the requested DUMP operation before discontinuing the 
processing. It will also dump a hexadecimal image of the module IEEVLNKT to 
the SYSPRINT data set. 


REP Control Statement 
causes SPZAP to replace the data at offset X'0018' in module IEEVLNKT with 
the data given in this control statement, provided the VERIFY statement was 
successful. , 
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SETSSI Control Statement 
instructs SPZAP to replace the system status information in the directory entry 
for module IEEVLNKT with the SSI data given in the statement, if the VERIFY 
statement was successful. The new SSI is to contain: 


e Achange level of 01. 
© A flag byte of 21. 
e A serial number of 1234. 


IDRDATA Control Statement 
causes SPZAP to update the IDR in module IEEVLNKT with the data 71144, if the 
REP operation is successful. 


DUMP Control Statement 
requests that a hexadecimal image of module IEEVLNKT be dumped to the 
SYSPRINT data set. Since the DUMP statement follows the REP statement, the 
image will reflect the changes made by SPZAP if the VERIFY operation was 
successful. 


Example 2: Inspecting and Modifying a CSECT in a Load Module Containing 
Several CSECTs 


This example shows how to apply an IBM-supplied PTF in the form of an SPZAP fix, 
rather than a module replacement PTF. 


//PTF40228 JOB MSGLEVEL=(1,1) 
//STEP EXEC PGM=AMASPZAP 
//SYSPRINT DD SYSOUT=A 
//SYSLIB. ODD DSNAME=SYS1. NUCLEUS , DISP=OLD 
//SYSIN DD * | 
NAME IEANUCO1 IEWFETCH 
IDRDATA LOCFIX01 


VERIFY O1FO 47F0CO18 
VERIFY 0210 5830C8F4 
O01FO 4780C072 
0210 4130C8F4 
02114228 
TEANUCO1] IEWFETCH 


SYSLIB DD Statement 
defines the library (SYS1.NUCLEUS) that contains input module IEANUCO1. 


SYSIN DD Statement | 
defines the input stream that contains the SPZAP control statements. 


NAME Control Statement 
instructs SPZAP that the operations defined by the contro] statements that 
immediately follow this statement are to be performed on the CSECT IEWFETCH | 
contained in the load module IEANUCOT. 


IDRDATA Control Statement 
causes SPZAP to update the IDR in module IEANUCOT for CSECT IEWFETCH 
with the date LOCFIX01, if either of the REP operations is successful. 


4-22 Service Aids 


VERIFY Control Statements 
request that SPZAP compare the contents of the locations X'01FO' and X'0210' 
in the control section IEWFETCH with the data given in the VERIFY control 
statements. If the comparisons are equal, SPZAP continues processing 
subsequent control statements sequentially. However, if the data at the 
locations does not compare identically to the data given in the VERIFY control 
statements, SPZAP dumps a hexadecimal image of CSECT IEWFETCH to the 
SYSPRINT data set; the subsequent REP and SETSSI statements are ignored. 
The DUMPT function specified will be performed before SPZAP terminates 
processing. 


REP Control Statements 
cause SPZAP to replace the data at offsets X'01F0' and X'0210' from the start 
of CSECT IEWFETCH with the hexadecimal data specified on the corresponding 
REP statements. 


SETSSI Control Statement 
causes SPZAP to replace the system status information in the directory for 
module IEANUC01 with the SSI data given in the SETSSI statement after the 
replacement operations have been effected. The new SSI will contain: 


¢ A change level of 02. 
e A flag byte of 11. 
e A serial number of 4228. 


DUMPT Control Statement 
causes SPZAP to produce a translated dump for CSECT IEWFETCH of load 
module IEANUCO1. 


Example 3: Inspecting and Modifying Two CSECTs in the Same Load Module 


This example shows how to inspect and modify two control sections in the same 
module. 


//CHANGIT JOB MSGLEVEL=(1, 1) 
//STEP EXEC PGM=AMASPZAP 
//SYSPRINT DD SYSOUT=A 
//SYSLIB DD DSNAME=SYS1. LINKLIB,DISP=OLD 
//SYSIN DD * 
NAME IEFX5000 IEFQMSSS 
VERIFY 0284 4780,C096 
REP 0284 4770,C096 
IDRDATA PTF01483 


SETSSI 01212448 


DUMPT IEFX5000 IEFQMSSS 
NAME IEFX5000 IEFQMRAW 
VERIFY 0154 4780,C042 

REP Q154 4770,C042 
IDRDATA  PTFO1483 

SETSSI 01212448 

DUMPT IEFX5000 IEFQMRAW 


[* 
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SYSLIB DD Statement 7 
defines the data set to be accessed by SPZAP while sermon the operations 
specified by the control statements. In this case, it defines the system library 
SYS1.LINKLIB containing the load module IEFX5000 that is to be changed by 
SPZAP. 


NAME Conirol Statement #1 
instructs SPZAP that the operations requested via the control statements 
immediately following it are to be performed on CSECT IEFQMSSS in load 
module IEFX5000 that resides in the data set defined by the SYSLIB DD 
statement. 


VERIFY Control Statement #1 
requests that SPZAP check the hexadecimal data at offset X'0284' in CSECT 
IEFQMSSS to make sure it is the same as the data specified in this control 
statement. If the data is identical, SPZAP continues processing the control 
statements. If the data is not identical, SPZAP does not perform the REP or 
-SETSSI for CSECT IEFQMSSS, but it does perform the DUMPT operation. It also 
provides a hexadecimal dump of CSECT IEFQMSSS. 


REP Controi Statement #1 
causes SPZAP to replace the data at offset X'0284' in CSECT IEFQMSSS with 
the hexadecimal data given in this control statement. 


IDRDATA Control Statement #1 
causes SPZAP to update the IDR in module IEFX5000 for CSECT IEFQMSSS with 
the data PTF01483, if the first REP operation is successful. 


SETSSI Control Statement #1 
instructs SPZAP to replace the system status information in the directory entry 
for module IEFX5000 with the SSI data given. The new SSI will contain: 


e A change level of 01. 
¢ A flag byte of 21. 
e A serial number of 2448. 


DUMPT Control Statement #1 
causes SPZAP to provide a translated dump of CSECT IEFQMSSS. 


NAME Control Statement #2 
indicates that the operations defined by the control statements that immediately 
follow this statement are to be performed on CSECT IEFQMRAW in the load 
module IEFX5000. 


VERIFY Control Statement #2 
requests that SPZAP perform the VERIFY function at offset X'0154' from the 
start of CSECT IEFQMRAW. If the VERIFY operation is successful, SPZAP 
continues processing the subsequent control statements sequentially. If the 
VERIFY is rejected, however, SPZAP does not perform the following REP or 
SETSS! operations, but it does dump a hexadecimal image of CSECT 
IEFQMRAW to the SYSPRINT data set and performs the DUMPT operation as 
requested. 


REP Control Statement #2 
causes SPZAP to replace the data at hexadecimal offset X'0154' from the start 
of CSECT IEFQMRAW with the hexadecimal data that is specified in this control 
statement. 


IDRDATA Control Statement #2 
causes SPZAP to update the IDR in module IEFX5000 for CSECT IEFQMRAW 
with the data PTF01483, if the second REP operation is successful. 


SETSSI Control Statement #2 
causes SPZAP to perform the same function as the previous SETSSI, but only if 
the second VERIFY is not rejected. 


DUMPT Control Statement #2 
causes SPZAP to perform the DUMPT function on control section IEFQMRAW. 


Example 4: Inspecting and Modifying a Data Record 


In this example, the data set to be modified is a volume table of contents. 


//ZAPIT JOB MSGLEVEL=(1, 1) 

//STEP EXEC PGM=AMASPZAP 
//SYSPRINT DD SYSOUT=A 

//SYSLIB DD DSNAME=FORMAT4. DSCB,DISP=OLD, 
// UNIT=3330, VOLUME=SER=111111,DCB=(KEYLEN=44) 
//SYSIN DD * 

CCHHR 0005000001 

VERIFY 2c 0504 

REP 2C 0A08 

REP —— 2E-~—-Q001,03000102 

ABSDUMPT ALL 
/* 


SYSPRINT DD Statement 
defines the message data set. 


SYSLIB DD Statement 
defines the data set to be accessed by SPZAP in performing the operations 
specified by the control statements. In this example, it defines the VTOC (a 
Format 4 DSCB) on a 3330 volume with a serial number of 111111. 
DCB = (KEYLEN = 44) is specified so that the dump produced by the ABSDUMPT 
control statement will show the dsname which is a 44-byte key. Note that this is 
not necessary for the VERIFY and REP control statements. 


CCHHR Control Statement 
indicates that SPZAP is to access the direct access record address 
“0005000001” in the data set defined by the SYSLIB DD statement while 
performing the operations specified by the following control statements. 


VERIFY Control Statement 
requests that SPZAP check the data at hexadecimal displacement X'2C' from 
the start of the data record defined in the CCHHR statement to make sure it is 
the same as the hexadecimal data specified in this control statement. If the data 
is the same, SPZAP continues processing the following control statements 
sequentially. If the data is not identical, SPZAP does not perform the REP 
function but does perform the ABSDUMPT operation; it also dumps a formatted 
hexadecimal image of the data record defined by the CCHHR statement to the 
SYSPRINT data set. 
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REP Control Statements | 
cause the eight bytes of data starting at displacement 2C from the beginning of 
the record to be replaced with the hexadecimal data in the REP control 
statements. The 2C displacement value allows for a 44-byte key at the 
beginning of the record. 


ABSDUMPT Control Statement 
causes SPZAP to dump the entire data set to the SYSPRINT data set. Since 
DCB =(KEYLEN = 44) is specified on the SYSLIB DD statement, the 44-byte 
dsname is also dumped. | | | 


Note: If the VTOC is to be modified, message AMA117D is to be issued to the 
operator, requesting permission for the modification. 


Example 5: Entering SPZAP Control Statements Through the Console 


This example shows how to enter SPZAP control statements through the console. 


//CONSOLIN JOB MSGLEVEL=(1,1) 

//STEP EXEC PGM=AMASPZAP 

//SYSPRINT DD SYSOUT=A 

//SYSLIB = DD” DSNAME=SYS1.LINKLIB,DISP=OLD | 


//SYSIN DD * 
CONSOLE 
/* 


SYSLIB DD Statement 
defines the data set that contains the module to be updated. 


SYSIN DD Statement 
defines the input stream. 


CONSOLE Control Statement 
indicates that SPZAP control statements are to be entered through the console. 


Example 6: Using the BASE Control Statement for Inspecting and Modifying a 


Load Module 
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This example shows how to inspect and modify a CSECT whose starting address 
does not coincide with assembly listing location zero. 


//MODIFY JOB MSGLEVEL=(1,1) 
//STEP . EXEC PGM=AMASPZAP 
//SYSPRINT DD SYSOUT=A 
//SYSLIB = DD DSNAME=SYS1.LINKLIB,DISP=OLD 
//SYSIN DD * 

NAME | IEFMCVOL IEFCVOL2 

BASE 0398 

IDRDATA MODO4 

VERIFY 039A 5820C010 

REP 039A 47000000 

DUMP IEFMCVOL IEFCVOL2 
hai 


SYSLIB DD Statement 
defines the data set to be accessed by SPZAP when performing the operations 
requested via the control statements. In this case, it defines the system library, 
SYS1.LINKLIB, that contains the module IEFMCVOL in which the CSECT to be 
changed, IEFCVOL2, resides. 


SYSIN DD Statement 
defines the input stream that contains the SPZAP control statements. 


NAME Control Statement 
instructs SPZAP that the operations defined by the control statements that 
immediately follow it are to be performed on CSECT IEFCVOL2 in the load 
module IEFMCVOL. 


BASE Control Statement 
provides SPZAP with a base value that is to be used to readjust the offsets on 
the VERIFY and REP statements that follow it. | 


IDRDATA Control Statement 
causes SPZAP to update the IDR in module IEFMCVOL for CSECT IEFCVOL2 
with the data MOD04, if the REP operation is successful. 


VERIFY Control Statement 
requests that SPZAP inspect the data at offset X'039A'. The base value 
X'0398' given in the previous BASE statement is subtracted from this offset to 
determine the proper displacement of the data within CSECT IEFCVOL2. 
Therefore, SPZAP checks the data at the location that is actually displaced 
X'0002' bytes from the beginning of CSECT IEFCVOL2 to ensure that it is the 
same as the hexadecimal data specified in this control statement. If the data is 
the same, SPZAP continues processing the following statements in the order in 
which they are encountered. If the data is not identical, SPZAP does not 
perform the REP, SETSSI, or IDRDATA functions, but it does perform the DUMPs 
operation; it also dumps a hexadecimal image of CSECT IEFCVOL2 to the 
SYSPRINT data set. 


REP Control Statement 
causes SPZAP to replace the data at displacement X'0002' (offset 039A minus 
base value 0398) into CSECT IEFCVOL2 with the hexadecimal data specified in 
this control statement. 


DUMP Control Statement 
requests that SPZAP dump a hexadecimal image of CSECT IEFCVOL2 to the 
SYSPRINT data set. Since the DUMP statement follows the REP statement, the 
image will reflect the changes made by SPZAP (assuming no verification has 
been rejected). 
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_ Abbreviation 


AID 
ASCB 
ASID 
ASXB 
ASVT 
ASMVT 
BCB 
BSAM 
CCT 
CCW 
CDE 
CESD 
CHPID 
COM 
CS 
CSCB 
CSCH 
CSD 
CSECT 
CVT 
DA 
DCB 
DEB 
DLIB 
DQE 
DS 
DSCB 
EBCDIC 
ECB 
EID 
EOF 
EOV 
EP 
EPA 
ERB 
EREP 
ESD 
FID 
FSS 
FXTAB 
GSMQ 
GSPL 
GTF 
GTFBCB 
GTFBLOK 
GTFBUFR 
GTFPCT 
HSCH 
ICR 
IDR 
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Chapter 5. Abbreviation Dictionary 


Meaning 


record identifier 

address space control block 

address space identifier 

address space control block extension 
address space vector table 

auxiliary storage manager vector table 
buffer control block 

basic sequential access method 
common control table 

channel command word 

contents directory entry 

composite external symbol dictionary 
channel path identifier 

common communication area 

control section name 

command scheduling control block 
clear subchannel 

common system data area 

control section 

communication vector table 

data area or direct access 

data control block 

data extent block 

distribution library 

description queue element 

data set 

data set control block 


extended binary-coded-decimal-interchange code 


event control block 
event identifier 

end of file 

end of volume 

entry point name 
entry point address 
error recovery block 


environmental record error and printing program 


external symbol dictionary 
format identifier 

functional subsystem 

fix table 

global service manage queue 
global service priority list queue 


generalized trace facility service aid program 


GTF buffer control block 

GTF blocking area 

GTF buffer 

GTF primary control table 

halt subchannel 

independent component release 
CSECT identification record 
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INITDATA 
I/O 

lOS 

IPL 

lQE. 

JCL 
JFCB 
JOBNAME 
LCCA 
LCCAVT 
LGVT 
LIST 
LLE 

LPA 
LPID 
LPRB 

LR 
LRECL 
LSMQ 
LSPL 
LSQA 
LT 

LTH 

MC 
MCAWSA 
MCCD 
MCCE 
MCCLE 
MCED 
MCEE 
MCHEAD 
MCQE 
MCRWSA 
MN 
MSCH 
PCB 

PCl 

PDS 


PDSE 


PER 
PICA 
PSW 
PTF 
QCB 
QCR 
QEL 


RANGETAB 


RB 
RCSW 
RE 
RECFM 
RLD 
RNIO 
RQE 
SADMP 
SCSW 


initialization data 

input/output 

input/output supervisor 

initial program load 

interruption queue element 

job control language 

job file control block 

jobname | 

logical configuration communication area 
logical configuration communication area vector table 
logical group vector table 
AMBLIST service aid program 
load list element 

link pack area 

logical page identifier 

loaded program request block 
label reference 

logical record length 

logical service manage queue 
logical service priority list 

local system queue area 

logical track 

logical track header 

monitor call 

monitor call application work/save area 
monitor call class directory | 
monitor call control element 
monitor call class element 
monitor call event directory 
monitor call event element 
monitor call base table 

monitor call queue element 
monitor call router work/save area 
module name 

modify subchannel 

print control block 

program controlled interruption 
partitioned data set | 
partitioned data set extended 
program event recording 
program interruption control area 
program status word 

program temporary fix 

queue control block 

queue control record 

queue element 

range table 

request block 

real channel status word 

record entry 

record format 

relocatable load dictionary 
remote network input/output 
reply queue element 
AMDSADMP service aid program 
subchannel status word 


SD 
SDATA 
SLE 
SLH 
SLIP 
SMP 
SPZAP 
SQA 
SR 
SSCH 
SSI 
STA 
SVC 
SYSGEN 
SYSIN 
~SYSOUT 
TCAM 
TCB 
TIOT 
TOD 
TQE 
TTR 
UCB 
VCCT 
VOLID 
VPA 
VS 


section definition 
service data area 
save list element 
subchannel logout handler 


serviceability level indication processing 


System Modification Program 
AMASPZAP service aid program 
system queue area 

subroutine 

start subchanne! 

system index status 

starting address 

supervisor call 

system generation 

system input 

system output 
telecommunications access method 
task control block 

task input/output table 

time of day 

timer queue element 

relative trace and record address 
unit control block 

virtual common communications table 
volume identification 

virtual page address 

virtual storage 
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5-4 Service Aids 


index 


A 


abbreviation dictionary 
SADMP service aid 5-1 
abbreviations for service aid names _ xii 
ABDUMP= parameter 
inGTF 1-2, 1-4, 1-5 
ABEND dump 
including trace data 1-2 
ABSDUMP/ABSDUMPT control statement 
example 4-26 
inSPZAP 4-5, 4-15, 4-26 
parameter 4-15 
AB= parameter 
inGTF 1-5 
ADDR= parameter 
of AMDSADMP macro_ 3-9 
AMASPZAP service aid xii 
See also SPZAP service aid 
AMA112I 4-4 
AMBLIST service aid xii 
See also LIST service aid 
AMDSADMP macro 
assembly 3-10 
example 3-35 
format for high-speed dump 3-6 
low-speed dump 3-8 
low-speed dump, format 3-8 
multiple versions, assembling 3-12 
parameter 
ADDR=_ 3-9 
CONSOLE= 3-7, 3-9 
DUMP 3-19 
DUMP= _ 3-7 
IPL= 3-6, 3-8 
LOADPT=_ 3-7, 3-10 
MINASID 3-8 
MSG= 3-8, 3-10 
OUTPUT= __—3-7,, 3-9 
PROMPT 3-7, 3-19 
SYSUT= 3-7, 3-9 
TYPE= __3-6, 3-8 
ULABEL= _ 3-6, 3-9 
VOLSER=__ 3-6, 3-9 
sample JCL 3-11 
symbol 3-6, 3-8, 3-12 
syntax 
for high-speed dump 3-6 
SYS1.MACLIB data set 
assembly 3-11 
two-stage generation 3-10 
AMDSADMP service aid xii 
See also SADMP service aid 
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application identifier 
See AID 

applying fixes xii 

ASID option 
for SADMP__ 3-21 

ASIDP trace option 
description 1-9 
inGTF_ 1-9, 1-17 
prompting 1-13, 1-17 


BASE control statement 
example 4-27 
inSPZAP 4-3, 4-16, 4-27 
parameter 4-16 

BUF= parameter 
inGTF 1-4, 1-5 


C 


CANCEL command 1-24 
catalog 
rebuilding 4-8 
cataloged procedure 
GTF 1-3, 1-7 
CCHHR control statement 
inSPZAP 4-4, 4-12 
parameter 4-12 
CCW trace option 
combining certain trace options 1-12 
description 1-9 
inGTF 1-9, 1-12 
CCWN= parameter of GIF CCWP_ 1-18, 1-14 
CCWP trace option 
combining certain trace options 1-12 
description 1-9 
inGTF 1-9, 1-12, 1-13, 1-14, 1-15 


parameter 
CCWN= 1-14 
DATA= 1-14 
IOSB 1-15 
PCITAB. 1-15 
S|I|SI 1-14 


prompting 1-13 
central (also called real) storage dump 
description 3-1 
of SADMP_ 3-2 
changing the name of the trace dataset 1-19 
channel program data 
record 1-9 
CHECKSUM control statement 
inSPZAP 4-17 
parameter 4-17 


X-1 


choosing a service aid xii 
clear subchannel operation 
record 1-9 
code | 
See return code, wait reason code 
combination of LIST control statement 2-3 
combining GTF trace options 1-12 
comment control statement 
See * control statement in SPZAP 
console communication 
inGTF 1-8, 1-13, 1-18 
in SADMP_ 3-28 
CONSOLE control statement 
example 4-26 
inSPZAP 4-16, 4-26 
consoles supported by SADMP 3-7, 3-9 
CONSOLE = parameter 
of AMDSADMP macro 3-9 
CONSOLE = parameter of 
AMDSADMP macro 3-7 
control statement 
for LIST 2-3 
for SPZAP 4-11 
copying dumps 
tape toDASD 3-32 
cross-reference list 
LIST output 2-6 
CSA dumped by SADMP__ 3-2 
CSCH trace option 
combining certain trace options 1-12 
description 1-9 
inGTF 1-9, 1-12 
CSECT identification record 
print 2-1 
CSECT name 
NAME control statement 
of SPZAP 4-2 


D 


data 
inspecting with SPZAP 4-2 
modifying with SPZAP 4-2 
DATASPACES option 
for stand-alone dump 3-22 


DATA= parameter of GTF CCWP_ 1-13, 1-14 


DD statement 

in LIST 
anyname 2-2 
SYSIN 2-2 
SYSPRINT 2-2 

in SADMP _ 3-5, 3-32 
SYSIN 3-18 
SYSPRINT 3-18 
SYSPUNCH 3-11 

in SPZAP 

~ SYSABEND 4-8 
SYSIN 4-8, 4-21, 4-22, 4-26, 4-27 


SYSLIB 4-2, 4-7, 4-21, 4-22, 4-24, 4-25, 4-26, 4-27 
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DD statement (continued) 
in SPZAP (continued) 
SYSPRINT 4-7, 4-25 
SYSLIB 3-5 
SYSUT2 3-32 
DDN= parameter 
LISTIDR control statement 2-5 
LISTLOAD control statement 2-3 
LISTOBJ control statement 2-4 
DEBUG option 
of SLIP 1-10 
DEBUG= parameter 
inGTF 1-4, 1-6 
DEBUG=NO_ 1-6 
DEBUG=YES_ 1-6 
devname 
on START command for GTF_ 1-3 
DISP parameter 
output data set specification 1-6 
dispatchable units of work 
record 1-9 
DSNAME parameter 
changing the name of the trace data set 
DSP trace option 
description 1-9 
inGTF 1-9 
DUMP command 3-23 
DUMP control statement 
inSPZAP 4-5 
DUMP parameter 
of AMDSADMP macro. 3-7, 3-19 
dump tailoring option 
for SADMP_ 3-20 
dump title 
in LIST 
LISTIDR control statement 2-4, 2-5 
LISTLOAD control statement 2-3 
LISTOBJ control statement 2-4 
specification 2-3, 2-4, 2-5 
specification in SADMP_ 3-28 
DUMP/DUMPT control statement 
example 4-22, 4-23, 4-24, 4-25, 4-27 


inSPZAP 4-14, 4-15, 4-22, 4-23, 4-24, 4-25, 4-27 


parameter 4-14, 4-15 
dvolser 3-31 
dynamic invocation 

of SPZAP 4-9 


E 


EID assignment 
user event 1-27 
END keyword : 
in GTF prompting 1-13, 1-17, 1-21 
EREP xii 
error recovery 1-28 
ESTAE operation 
record 1-10 


1-6 


event identifier 
See EID 
example 
of using GTF_ 1-18 
of using LIST 2-15 
of using SADMP_ 3-35 
of using SPZAP 4-21 
EXEC statement 
in GTF cataloged procedure 1-7 
EXT trace option 
combining certain trace options 1-12 
description 1-9 
inGTF_ 1-9, 1-12 
external interruption 
record 1-9 


- 


filter routine 
handling errors 1-28 
fixed link pack area 
map 2-5 
fixes xii 
FLPA parameter 
of LISTLPA (LIST) 2-5 
FORCE ARM command 1-24 
FORCE command 1-24 
format identifier 
See FID 
formatted dump 3-2 
formatted dump program 
example 3-36 
Formatted SADMP printing 3-32 
formatting and printing service aids xii 
FRR data 
record 1-10 
functional recovery routine data 
record 1-10 


G 


generalized trace facility xii 
See also GTF 
generating and applying fixes xii 
GTF cataloged procedure 
EXEC statement 1-7 
IEFRDER DD statement 1-7 
PROC statement 1-7 
SYSLIB DD statement 1-7 
GTF START command parameter 
devname 1-3 
example’ 1-3 
identifier 1-3 
keyword= option 1-3, 1-6 
MEMBER=__ 1-6 
parm member 
ABDUMP= _ 1-4, 1-5 
BLOK= 1-5 
BUF= _ 1-4, 1-5 


GTF START command parameter (continued) 


parm member (continued) 
DEBUG= ___ 1-4, 1-6 
MODE=_ 1-4 
SADMP=_ 1-4 
SDUMP= __ 1-4, 1-5 
specifying on the START command 1-3 
TIME= 1-4, 1-5 
procname 1-3 
volserial 1-3, 1-4 


GTF trace event 


record 1-11 


GTF trace option 


ASIDP 1-9 

CCWP 1-9 

combining certain options 1-12 
CSCH_ 1-9 

DSP 1-9 

EXT 1-9 

HSCH 1-9 
in SYS1.PARMLIB 1-7, 1-8 
JOBNAMEP _ 1-9 

MSCH 1-9 

PCI 1-10 

PI 1-10 

PIP 1-10 

prompting for 1-13 
RNIO- 1-10 

RR 1-10 

SLIP 1-10 

specification 1-8 
specifying 1-18 

SRM_ 1-10 

SSCH_ 1-10 

SSCHP 1-10 

storing 1-19 
summary of 1-9 

SVC 1-11 

SVCP_ 1-11 

SYS, SYSM, SYSP__1-11 
TRC 1-11 

USR, USRP_ 1-11, 1-12 


GTF trace options 


in SYS1.PARMLIB 
storage 1-19 


GTF trace record format 


comprehensive 1-2 
minimal 1-2 


GTF (generalized trace facility) 


AFFINITY macro 1-1 
cataloged procedure 
EXEC statement 1-7 
IEFRDER DD statement 1-7 
inSYS1.PROCLIB 1-7 
PROC statement 1-7 
SYSLIB DD statement 1-7 
combining certain trace options 1-12 
description xi, 1-1 


index 


X-3 


GTF (generalized trace facility) (continued) 
error recovery handling 1-28 
example 1-18 
function xii 
GTF usage 1-2 
initialization 

example 1-18 
specify trace option 1-18 
output 
deferred mode 1-2 
external mode 1-2 
internal mode 1-2 
prompting 1-13 
recording user data 
coding the GTRACE macro _ 1-27 
printing user data 1-27 
starting GTF 
cataloged procedure 1-3 
example 1-7 
how to start 1-3 
prompting 1-13 
specify trace option 1-8 
START command 1-3 
storing trace options in SYS1.PARMLIB 
STOP command 1-24 
storage requirement 1-26 
system trace 1-1 
trace optionsummary 1-9 
trace output 1-2, 1-19 
trace output retrieval 1-2 
trace VTAM remote network activity 1-22 
user trace data 1-27 
31-bit addressing support 1-1 
GTFPARM parameter 1-3, 1-6, 1-7 
GTRACE header in data field of GTF user trace 
record 1-27 

GTRACE macro 
addressing mode 1-1 
effect on EDIT user program 1-27 
function 1-27 
recording user trace data 1-27 


H 


halt subchannel operation 
record 1-9 
high speed dump 3-2 
high speed dump program 
example 3-35 
high-speed version 
of SADMP_ 3-6 
high-speed version of SADMP_ 3-2 
HSCH trace option 
combining certain trace options 1-12 
description 1-9 
inGTF 1-9, 1-12 


X-4 Service Aids 


I 
identifier 
on START command for GTF_ 1-3 
IDRDATA control statement 
example 4-22, 4-24, 4-25, 4-27 © 
inSPZAP 4-14, 4-22, 4-24, 4-25, 4-27 
parameter 4-14 
IEBGENER utility 3-32 
IEBPTPCH utility 3-1 
IEFRDER DD statement 
in GTF cataloged procedure’ 1-7 
information gathering service aids xii 
initial status request interruption 
record 1-10 
initialization error messages 
in SADMP_ 3-13 
inspecting data 
using SPZAP 4-2 
instruction address trace 3-2 
interactive problem control system 
See IPCS 
intermediate status interruption 
record 1-10 
internal trace 
request 1-4, 1-18 
interruption 
code 1-10, 1-16 
external 1-9 
initial status request 1-10 
intermediate status 1-10 
VO 1-9, 1-15. 
program 1-10, 1-16 
program-controlled 1-10 
resume channel program’ 1-10 
supervisor (SVC) 1-11, 1-16 
suspend channel program’ 1-10 
lO trace option 
combining certain trace options 1-12 
description 1-9 
inGTF 1-9, 1-12 
IOP trace option 
combining certain trace options 1-12 
description 1-9 
inGTF 1-9, 1-12, 1-15 
prompting 1-15 
lIOSB parameter of GTF CCWP_ 1-13, 1-15 
lO=SSCH= prompting 1-16, 1-17 
IPCS (interactive problem control system) 
IPL= parameter 
of AMDSADMP macro _ 3-6, 3-8 
1/O GTFBLOK 
how to request 1-5 
I/O interruption 
record 1-9 


Xi 


J 


JCL statement 
LIST service aid 2-2, 2-15 
SADMP program 3-34 
SPZAP service aid 4-7 
JOBNAMEP trace option 
description 1-9 
inGTF 1-9, 1-16 
prompting 1-16 


K 


keyword=option 1-6 


L 


link pack area 
LIST service aid 2-5 
map 2-5 
lista link pack area 2-5 
lista load module 2-3 
list CSECT identification record 2-4 
LIST service aid 
control statement 
LISTIDR 2-4 
LISTLOAD 2-3, 4-5 
LISTLPA 2-5 
LISTOBJ 2-4 
rules for coding 2-3 
description xi 
example 2-15 
function § xii, 2-1 
JCL statement 2-2 
mapping CSECTs ina load module 2-1 
Output 2-6 
verification of an object model 2-1 
verification of nucleus contents 2-1 
LISTIDR control statement 
example 2-17, 2-19, 2-20 
format 2-4 
iINnLIST 2-4, 2-5, 2-7, 2-17, 2-19, 2-20 
output 2-7 
parameter 
DDN= 2-5 
MEMBER= 2-5 
MODLIB 2-5 
OUTPUT= 2-4 
TITLE= 2-5 
LISTLOAD control statement 
example 2-16, 2-19, 2-20 
format 2-3 
iNLIST 2-3, 2-4, 2-6, 2-16, 2-19, 2-20, 4-5 
Output 2-6 
parameter 
DDN= 2-3 
MEMBER= 2-3 
OUTPUT= 2-3 
RELOC= 2-4 
TITLE= 2-3 


LISTLOAD control statement (continued) 
to listthe SSI 4-5 
LISTLPA control statement 
example 2-20 
format 2-5 
inLIST 2-5, 2-7, 2-20 
output 2-7 
parameter 
FLPA 2-5 
MLPA 2-5 
PLPA 2-5 
LISTOBJ control statement 
example 2-15, 2-18, 2-19 
format 2-4 
in LIST 2-4, 2-7, 2-15, 2-18, 2-19 
Output 2-7 
parameter 
DDN 2-4 
MEMBER= 2-4 
TITLE= 2-4 
load module list 
LIST output 2-3, 2-6, 2-16 
LOADPT = parameter 
of AMDSADMP macro _ 3-7, 3-10 
low speed dump 3-2 
low-speed version 
of SADMP_ 3-3, 3-8 
LPA map 
See link pack area, map 
LSQA dumped by SADMP 3-2 


macro expansion messages 
in SADMP_ 3-13 
main storage dump 
description 3-1 
of SADMP_ 3-2 
map 
link pack area 2-1, 2-5, 2-20 
load module 2-1 
nucleus 2-1, 2-20 
MEMBER= parameter 1-6 
LISTIDR control statement 2-5 
LISTLOAD control statement 2-3 
LISTOBJ control statement 2-4 
message 
from SPZAP 4-18 


GTF 1-8, 1-17, 1-18, 1-19, 1-20, 1-21, 1-22, 1-23 


SADMP program 3-28 
message display 

SADMP program 3-31 

3480 device 3-31 
MINASID parameter 

of AMDSADMP macro 3-8 
MLPA parameter 

of LISTLPA (LIST) 2-5 


Index 


MODE = parameter 
inGTF 1-4 
modified link pack area 
map 2-5 
modify subchannel operation 
record 1-9 
modifying data 
using SPZAP 4-2, 4-21, 4-25 
modifying data (SPZAP) 4-22, 4-23, 4-26 
MODLIB parameter 
of LISTIDR (LIST) 2-5 
module listing program xii 
MSCH trace option 
combining certain trace options 1-12 
description 1-9 
inGTF 1-9, 1-12 
MSG= parameter 
of AMDSADMP macro _ 3-8, 3-10 


N | 

NAME control statement 
example 4-21, 4-22, 4-24, 4-27 © 
inSPZAP 4-2, 4-11, 4-21, 4-22, 4-24, 4-27 
parameter 4-11 


notation for defining control statement parameters xiii 


nucleus 
map using LIST 2-1 


O 


object module list 

how to obtain 2-15 
of SADMP__3-33 
OPEN/CLOSE/EOV_ 1-12 
operator communication 

See message 

console communication 

output 3-32 

of GIF 1-28 

of LIST 2-6 

of SPZAP 4-18 
output space requirements 

of GTF 1-26 
OUTPUT= parameter 

LISTIDR control statement 2-4 

LISTLOAD control statement 2-3 

of AMDSADMP macro _ 3-7, 3-9 


p 


pageable link pack area 
map 2-5 
parameter 
of EXEC statement 
inGTF 1-7 
of GTF START command 1-3 


X-6 = Service Aids 


PARM option 
IGNIDRFULL 4-7 
of JCL EXEC statement 4-7 
for SPZAP service aid 4-7 
SPZAP 4-7 
PARM= parameter of EXEC statement 
in GTF cataloged procedure 
ABDUMP=_ 1-5 


BLOK= 1-5 
BUF= 1-4, 1-5 
DEBUG= 1-6 


keyword=_ _ 1-6 
MEMBER=_ 1-6 


MODE=_ 1-4 
SADMP=_ 1-4 
SDUMP=_ 1-5 
TIME=_ 1-5 


PCI trace option 
description 1-10 
inGTF 1-10 
PCITAB= parameter of GTF CCWP 1-13, 1-15 
PI trace option | 
combining certain trace options 1-12 
description 1-10 
inGTF 1-10, 1-12 
PIP trace option 
combining certain trace options 1-12 
description 1-10 
inGTF 1-10, 1-12, 1-16 
prompting 1-16 
PLPA parameter 
of LISTLPA (LIST) 2-5 
PROC statement 
in GTF cataloged procedure 1-7 
procname 
on START command for GTF_ 1-3 
program interruption 
record 1-10 
program interruption code’ 1-10 
program interruptions 
record 1-10 
program-controlled interruption 
record 1-10 
PROMPT parameter 
of AMDSADMP macro 3-7, 3-19 © 
prompting 
example 1-18 
how to request 1-13 
inGTF 1-13, 1-18 
PSA dumped by SADMP__ 3-2 


R 


RANGE option 
for SADMP_ 3-21 
reason code 
issued by SADMP__ 3-25, 3-27 


REGION parameter 
GTF cataloged procedure’ 1-6 
RELOC = parameter 
of LISTLOAD (LIST) 2-4 
remote network activity 
See RNIO 
REP control statement 
example 4-21, 4-23, 4-24, 4-27 
in SPZAP 4-2, 4-13, 4-21, 4-23, 4-24, 4-27 
variable 4-13 
resume channel program interruption 
record 1-10 
resume subchannel data 
how to record 1-10 
record 1-10 
return code 3-16 
from SPZAP 4-8 
RNIO trace option 
description 1-10 
in GTF 1-10 
RR trace option 
combining certain trace options 1-12 
description 1-10 
in GTF 1-10, 1-12 


S 
SADMP message 
display example 3-31 
MSADMP#U — 3-31 
NTRDY 3-31 
RSADMP# 3-31 
RSADMP# U_ 3-31 
SADMP#_ 3-31 
status information 
3480 device 3-31 
SADMP output 
description 3-2 
printing 3-32 
SADMP program variation 
description 3-2 
SADMP service aid 
abbreviation dictionary 5-1 
AMDSADMP macro 3-8 
coding 3-35 
assembly of the AMDSADMP macro 3-10 
central (also called real) storage 
print 3-32 
central (also called real) storage dump 3-2 
coding AMDSADMP macro 
for high-speed dump 3-6 
consideration 3-5 
copying dumps 
tape to DASD 3-32 
creation 3-4 
DD statement 3-18 
description xi 
device selection 3-4 


SADMP service aid (continued) 


DUMP command 3-23 
dump program execution 3-24, 3-25, 3-27 
dump specification 3-4 
dump tailoring option 3-20 
dump title specification 3-28 
dumping 3-27 
dumping additional storage 3-19, 3-20 
dvolser 3-31 
error condition 3-13 
example 3-35 
execution 3-19, 3-24 
execution procedure 3-24, 3-25, 3-27 
formatted output 3-32 
formatted printing 3-32 
function xii 
generation 
requesting additional storage 3-19 
IEBGENER utility 3-32 
IEBPTPCH utility 3-32 
initialization of residence volume _ 3-4, 3-16 
instruction address trace 3-2 
IPCS LIST subcommand 3-25 
IPLing and executing 3-24, 3-25 
JCL statement 3-34 
low-speed dump _ 3-8 
low-speed version 3-3 
macro message 3-16 


macro parameter 3-6, 3-7, 3-8, 3-9, 3-10, 3-12, 3-19 


main storage dump 3-2 
mapping 
nucleus 3-2 
message 3-28 
message output 3-13 
nucleus 3-2 
one-step generation 3-4, 3-16, 3-19 
output 3-32 
re-IPLing 3-24, 3-27 © 
reason code 3-25, 3-27 
residence volume initialization 3-4 
restart 3-24 
restarting SADMP_ 3-27 
return code 3-16 
sample console exchange 3-30 
sample JCL 3-11, 3-16 
self-dump 3-2, 3-24 
specification 
of address range 3-20 
of subpool 3-20 
storage dump 3-24 
system restart 3-25 
two-stage generation 3-4, 3-10, 3-16 
unformatted output 3-32 
used for self-dump 3-25 
using IPCS 3-32 
vector facility data 3-2 
virtual storage dump 3-2 
wait state 3-27 


Index 
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SADMP service aid (continued) 
wait state code 3-25 
wait-reason code 3-26, 3-27, 3-28 
processing completion 3-26 
3480 message 3-31 
SADMP = parameter 
inGTF 1-2, 1-4 
SA= parameter 
inGTF 1-4 
SDUMP= parameter 
inGTF 1-2, 1-4, 1-5 
SD= parameter 
inGTF 1-5 
self-dump 
of SADMP 3-2, 3-24 
service aid 
choosing xii 
GTF xii 
IPCS xii 
LIST xii 
SADMP =xii 
SPZAP xii 
summary xii 
serviceability level indication processing (SLIP) | 
See SLIP index entries 
SETSSI control statement 
example 4-22, 4-23, 4-24, 4-25 
inSPZAP 4-5, 4-14, 4-22, 4-23, 4-24, 4-25 
parameter 4-14 
SLIP data 
record 1-10 
SLIP trace option 
description 1-10 
inGTF 1-10 
SNAP dump 
including trace data 1-2 
SP option 
for SADMP 3-21 
SPZAP service aid 
access 
data record 4-4 
load module 4-2 
AMASPZAP program 4-1 
control statement 
ABSDUMP 4-5, 4-15, 4-26 
ABSDUMPT 4-15, 4-26 
BASE 4-3, 4-16, 4-27 
CCHHR 4-4, 4-12 
CHECKSUM 4-17 
CONSOLE 4-16, 4-26 
DUMP 4-5, 4-14, 4-22, 4-23, 4-24, 4-25, 4-27 
DUMPT 4-14, 4-22, 4-23, 4-24, 4-25, 4-27 
IDRDATA 4-14, 4-22, 4-24, 4-25, 4-27 
NAME 4-2, 4-11, 4-21, 4-22, 4-24, 4-27 
REP 4-2, 4-13, 4-21, 4-23, 4-24, 4-27 
rules for coding 4-11 
SETSSI 4-5, 4-14, 4-22, 4-23, 4-24, 4-25 
VERIFY 4-2, 4-12, 4-21, 4-23, 4-24, 4-27 
* 4-16 


X-8 Service Aids 


SPZAP service aid (continued) 
data modification and inspection 4-2 
data record 
inspection 4-4 
modification 4-4 
description § xi 
dumping data 4-5 
dynamic invocation 
example 4-10 
macro form 4-9 
example 4-21 
executing SPZAP 4-21 
JCL statement 4-7 
load module 
inspection 4-2 
modification 4-2 
monitoring SPZAP use 4-1 
operational consideration 4-6 
output 4-18 
return code 4-8 
updating system status information 4-5 
SQA dumped by SADMP_ 3-2 
SRM data 
record 1-10 
SRM trace option 
description 1-10 
inGTF_ 1-10 
SSCH trace option 
combining certain trace options 1-12 
description 1-10 
in GTF 1-10, 1-12 
SSCHP trace option 
combining certain trace options 1-12 
description 1-10 
inGTF 1-10, 1-12, 1-16 
prompting 1-16 
STAE operation 
record 1-10 
stand-alone dump program xii 
START command _ 1-3, 1-19, 1-24 
start subchannel data 
record 1-10 
STOP command 1-24 
storage 
See central (also called real) storage 
virtual storage 
storage requirements 
for GTF 1-26 | 
STORE STATUS command 3-2, 3-25, 3-26, 3-27 
subpools dumped by SADMP_ 3-2 
superzap (data checker and modifier) xii 
suspend channel program interruption 
record 1-10 
SVC dump 
including trace data 1-2 
SVC interruption 
record 1-11 


SVC trace option 
combining certain trace options 1-12 
description 1-11 
in GTF 1-11, 1-12 
SVCP trace option 
combining certain trace options 1-12 
description 1-11 
inGTF 1-11, 1-12, 1-16 
prompting 1-16 
SYS trace option 
combining certain trace options 1-12 
description 1-11 
inGTF 1-11, 1-12 
SYSABEND DD statement 4-8 
SYSIN DD statement 4-8, 4-21, 4-22, 4-26, 4-27 
in SADMP_ 3-18 
used in LIST 2-2 
used in SPZAP 4-26 
SYSLIB DD statement 4-2, 4-7, 4-21, 4-22, 4-24, 4-25, 
4-26, 4-27 
in SADMP_ 3-5 
used in GTF_ 1-7, 1-20 
usedinSPZAP 4-26 
SYSM trace option 
combining certain trace options 1-12 
description 1-11 
inGTF 1-11, 1-12 
SYSP trace option 
combining certain trace options 1-12 
description 1-11 
inGTF 1-11, 1-12 
SYSPRINT DD statement 4-7, 4-25 
inSADMP_ 3-18 
used in LIST 2-2 
SYSPUNCH DD statement 
in SADMP_ 3-11 
system event 
trace with GTF 1-1 
system resource manager data 
record 1-10 
system restart 
for SADMP 3-25 
system status index 
function 4-5 
system status index (SSI) 
field 4-5 
flag byte 4-5, 4-6 
system trace 1-1 
SYSUT2 DD statement 3-32 
SYSUT= parameter 
of AMDSADMP macro _ 3-7, 3-9 
SYS1.LPALIB library 4-7 
SYS1.MACLIB 3-1 
AMDSADMP macro instruction 
assembly 3-11 
SYS1.PARMLIB library 1-3, 1-6, 1-7, 1-8 
SYS1.PROCLIB library 1-7 


SYS1.TRACE library 1-7 
S|I|S! parameter of GTF CCWP_ 1-14 


7 


timestamp record 
how to request 1-5 
TIME= parameter 
GTF 1-5 
inGTF 1-4 
TIME=NO_ 1-6 
TIME=YES_ 1-5 
title, specification 
See dump title, specification 
TITLE= parameter 
LISTIDR control statement 2-5 
LISTLOAD control statement 2-3 
LISTOBJ control statement 2-4 
trace buffers 
storage required 1-26 
trace dispatchable units of work 1-9 
trace option 
See GTF trace option 
trace record format 
comprehensive’ 1-2 
minimal 1-2 
tracing external interruption 1-9 
tracing functional recovery routine operation 1-10 
tracing halt subchannel operation 1-9 
tracing initial status request interruption 1-10 
tracing intermediate status interruption 1-10 
tracing I/O interruption 1-9 
tracing modify subchannel operation 1-9 
tracing program interruption 1-10 
tracing program-controlled interruption 1-10 
tracing resume channel program interruption 1-10 
tracing SLIP trap 1-10 
tracing suspend channel program interruption 1-10 
tracing VTAM network activity 1-10 
TRC trace option 
description 1-11 
inGTF 1-11 
TYPE= parameter 3-8 
of AMDSADMP macro _ 3-6, 3-8 


U 


ULABEL= parameter 
of AMDSADMP macro _ 3-6, 3-9 
unformatted dump 3-2 
unformatted dump program 
example 3-36 
user trace data 
record 1-11, 1-12 
USR trace option 
combining certain trace options 1-12 
description 1-11, 1-12 
inGTF 1-11, 1-12 
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USRP trace option 
combining certain trace options 1-12 
description 1-11, 1-12 
inGTF 1-11, 1-12, 1-16 
prompting 1-16 


V 


vector facility data 3-2 
VERIFY control statement 
example 4-21, 4-23, 4-24, 4-27 
inSPZAP 4-2, 4-12, 4-21, 4-23, 4-24, 4-27 
parameter 4-12 
virtual storage dump 
description 3-1 
of SADMP__ 3-2 
volserial 
on START command for GTF_ 1-4 
VOLSER= parameter 
of AMDSADMP macro _ 3-6, 3-9 
VSAM object 
accessing 4-8 
VTAM network activity 
record 1-10 


W 
wait state code 
issued by SADMP__ 3-25, 3-27 
wait-reason code 
issued by SADMP ___ 3-26, 3-27, 3-28 
unloading atape 3-26 


Special Characters 


* control statement 
inSPZAP 4-16 


X-10 = Service Aids 


MVS/ESA Service Aids READER'S 
COMMENT 
FORM 


GC28- 1844-2 


This manual is part of a library that serves as a reference source for systems analysts, programmers, and 
operators of IBM systems. You may use this form to communicate your comments about this publica- 
tion, its organization, or subject matter, with the understanding that IBM may use or distribute whatever 
information you supply in any way it believes appropriate without incurring any obligation to you. 

Note: Copies of IBM publications are not stocked at the location to which this form is addressed. Please 
direct any requests for copies of publications, or for assistance in using your IBM system, to your IBM 
representative or to the IBM branch office serving your locality. 

Possible topics for comment are: 


Clarity Accuracy Completeness Organization Coding Retrieval Legibility 


If you wish a reply, give your name, company, mailing address, and date: 


What is your occupation? 
How do you use this publication? 
Number of latest Newsletter associated with this publication: 


Thank you for your cooperation. No postage stamp necessary if mailed in the U.S.A. (Elsewhere, an 
IBM office or representative will be happy to forward your comments or you may mail directly to the 
address in the Edition Notice on the back of the title page.) 


MVS/ESA Service Aids 
GC28-1844-2 $370-37 


Reader's Comment Form 


Fold and Tape Please Do Not Staple 


Fold and Tape 


NO POSTAGE 
NECESSARY 


IF MAILED 


IN THE 


UNITED STATES 


BUSINESS REPLY MAIL 


FIRST CLASS cee NO. 40 ARMONK, 


POSTAGE WILL BE PAID BY ADDRESSEE 


International Business Machines Corporation 
Department D58, Building 921-2 

PO Box 950 

Poughkeepsie, New York 12602-9935 


Fold and Tape Please Do Not Staple 


Fold and Tape 


Printed tn U.S.A. 
| 


Program Number File Number 
5665-001 


$370-37 
5665-002 


UT 
@ I" 


GC28-1844-2 


